refactor tests

Reviewed-on: #4
Reviewed-by: StanPonomarev <dmss@krtss.de>

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.env.example

@@ -1,10 +1,10 @@
 GITEA_NETWORK=gitea
+AGENTCI_IMAGE=git.krtss.de/stanponomarev/agentci:latest
 AGENTCI_GITEA_URL=http://gitea:3000
 AGENTCI_BOT_USERNAME=agentci
 AGENTCI_BOT_NAME=Agent CI
 AGENTCI_BOT_EMAIL=agentci@localhost
 OPENCODE_SERVER_USERNAME=opencode
-AGENTCI_OPENCODE_VERSION=^1
 AGENTCI_PLAN_MODEL=openai/gpt-5.6-sol
 AGENTCI_PLAN_VARIANT=
 AGENTCI_IMPLEMENT_MODEL=openai/gpt-5.6-sol
@@ -18,9 +18,9 @@ AGENTCI_CONTEXT7_API_KEY=
 AGENTCI_PLAN_REVIEW_ROUNDS=4
 AGENTCI_IMPLEMENT_REVIEW_ROUNDS=3
 AGENTCI_TURN_TIMEOUT_SECONDS=3600
+AGENTCI_MAX_CONCURRENT_JOBS=2
 # Comma-delimited built-in or custom script names, for example: python,dotnet,company-tools
 AGENTCI_INSTALL_SCRIPTS=
 AGENTCI_INSTALL_SCRIPT_TIMEOUT_SECONDS=900
 AGENTCI_PYTHON_VERSION=3.13
 AGENTCI_DOTNET_CHANNEL=10.0
-CODEGRAPH_VERSION=1.3.1

.gitea/workflows/publish-image.yaml

@@ -0,0 +1,41 @@
+name: Publish container image
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  REGISTRY: git.krtss.de
+  IMAGE_NAME: git.krtss.de/stanponomarev/agentci
+
+jobs:
+  publish:
+    name: Build and push
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          pull: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:latest
+            ${{ env.IMAGE_NAME }}:${{ gitea.sha }}
+          labels: |
+            org.opencontainers.image.revision=${{ gitea.sha }}
+            org.opencontainers.image.source=${{ gitea.server_url }}/${{ gitea.repository }}

.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/agentci.iml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module external.system.id="pyproject.toml" type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="~/repos/agentci/.venv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/encodings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding" addBOMForNewFiles="with BOM under Windows, with no BOM otherwise" />
+</project>

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/agentci.iml" filepath="$PROJECT_DIR$/.idea/agentci.iml" />
+    </modules>
+  </component>
+</project>

.idea/pyLspTools.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PyToolsState">
+    <option name="tools">
+      <map>
+        <entry key="pyright">
+          <value>
+            <ToolEntry>
+              <option name="enabled" value="true" />
+            </ToolEntry>
+          </value>
+        </entry>
+        <entry key="ruff">
+          <value>
+            <ToolEntry>
+              <option name="enabled" value="true" />
+            </ToolEntry>
+          </value>
+        </entry>
+      </map>
+    </option>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

AGENTS.md

@@ -0,0 +1,133 @@
+# Agent CI repository instructions
+
+## Scope
+
+- These instructions apply to the whole repository. A nested `AGENTS.md` adds or overrides
+  instructions for its subtree; `opencode/AGENTS.md` contains runtime-specific guidance.
+- Agent CI is a private Gitea webhook service that turns issue and pull-request comments into
+  durable OpenCode workflows. Read `README.md` before changing command behavior, persistence,
+  recovery, deployment, or the security boundary.
+- Keep changes focused. Preserve unrelated work in a dirty worktree and do not rewrite code outside
+  the requested change merely for consistency.
+
+## Repository map
+
+- `src/agentci/engine/`: immutable domain models and events, the pure reducer, SQLite persistence,
+  task claiming, and the `JobRun` event interface.
+- `src/agentci/application/`: runtime composition, durable control/job queues, task handlers,
+  recovery, and comment reconciliation.
+- `src/agentci/workflows/`: planning, implementation, review, and pull-request orchestration.
+- `src/agentci/integrations/`: Gitea, Git, OpenCode, CodeGraph, and development external effects.
+- `src/agentci/api/`: FastAPI construction, lifespan, dependencies, errors, and HTTP routes.
+- `src/agentci/config/` and `src/agentci/observability/`: settings and structured logging.
+- `src/agentci/prompts/` and `src/agentci/prompts/schemas/`: model prompts and structured-output
+  contracts; keep these concerns outside Python orchestration.
+- `src/agentci/migrations/`: ordered SQLite migrations.
+- `tests/`: pytest suite, generally organized by module or behavior.
+- `compose.yaml`, `Dockerfile`, `scripts/`, `install-scripts/`, and `opencode/`: deployment and
+  trusted runtime configuration.
+
+## Setup and commands
+
+Use Python 3.13 or newer and `uv`. Run commands from the repository root.
+
+```sh
+uv sync
+```
+
+Run the narrowest relevant test while iterating:
+
+```sh
+uv run pytest tests/test_<area>.py
+uv run pytest tests/test_<area>.py::test_<behavior>
+uv run pytest -k '<expression>'
+```
+
+Run the standard Python checks before completion:
+
+```sh
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+Coverage is diagnostic and has no required threshold:
+
+```sh
+uv run pytest --cov=agentci --cov-branch
+```
+
+For deployment-related changes, also run:
+
+```sh
+docker compose config
+```
+
+Run `docker compose build` when changing dependencies, the image, runtime scripts, installers, or
+OpenCode configuration. It may require network access and takes longer than the normal checks.
+
+## Engineering conventions
+
+- Target Python 3.13, keep lines at or below 100 characters, and follow the Ruff and Pyright settings
+  in `pyproject.toml`. Use type annotations and existing modern Python patterns.
+- Keep jobs and workflows immutable. Domain snapshots use frozen dataclasses; create updated values
+  rather than mutating state in place.
+- Keep `engine/reducer.py` pure: no I/O, clocks, logging, or external calls. Express state changes as
+  events and task requests.
+- Apply state transitions, event persistence, and resulting task creation atomically through
+  `Repository`. The `jobs` table is the authoritative snapshot; timestamps are storage metadata.
+- Keep side effects in the worker, workflows, or top-level integration modules. Pass workflow
+  dependencies explicitly through `WorkflowServices` and progress through `JobRun`.
+- Preserve webhook/event idempotency, per-target FIFO execution, bounded unrelated concurrency, and
+  deterministic comment reconciliation.
+- Preserve restart semantics: queued work may resume, but an active partially executed model turn is
+  failed and its sessions are aborted rather than replayed.
+- Use structured logging fields such as `operation`, `job_id`, `stage`, and task identifiers. Never
+  log credentials, secret contents, authorization headers, or private prompt data.
+- Add a new numbered migration for schema changes. Never edit a migration that may already have been
+  applied.
+- Keep prompts and JSON schemas synchronized. Add or update tests when changing either contract.
+- Declare dependencies in `pyproject.toml` and let `uv` update `uv.lock`; do not edit the lockfile by
+  hand.
+
+## Testing conventions
+
+- Add regression tests for behavior changes, especially reducer transitions, persistence and
+  idempotency, restart recovery, queue ordering, webhook security, and integration error handling.
+- Prefer behavior-oriented test names, table-driven `pytest.mark.parametrize` cases, `tmp_path` for
+  filesystem/database isolation, and fake clients or `httpx.MockTransport` for external services.
+- Async tests run with `asyncio_mode = "auto"`; do not add an asyncio marker solely to make a test
+  asynchronous.
+- Assert externally meaningful state, emitted events/tasks, ordering, rendered comments, and safe
+  error text rather than private implementation details.
+- Do not make the default unit suite depend on live Gitea, OpenCode, provider credentials, Docker,
+  or network access.
+
+## Security and operational boundaries
+
+- Never commit or expose `.env`, `secrets/`, tokens, passwords, provider credentials, runtime data
+  directories, databases, cloned private repositories, or Docker volume contents. Do not send
+  secrets or private repository content to external search or research services.
+- Preserve webhook HMAC verification, bot-comment filtering, requester write-permission checks, and
+  secret-file loading.
+- OpenCode is not an OS sandbox. Do not weaken its permissions, enable repository-local configuration
+  or external skills, expose its server to the host, add privileged/capability settings, or add
+  writable host mounts beyond the documented `./data/agentci` and `./data/opencode` state directories
+  without an explicit security review.
+- `install-scripts/` is trusted operator code. Keep scripts idempotent, path-safe, and compatible with
+  the sanitized environment documented in `install-scripts/README.md`; never pass Agent CI or Gitea
+  credentials to them.
+- Git pushes performed by Agent CI must remain non-forcing.
+- Do not run provider authentication, start/restart deployment services, modify production data, or
+  perform other live operations unless the user explicitly requests it.
+- Do not edit or commit generated/local state in `.venv/`, `.pytest_cache/`, `.ruff_cache/`,
+  `.codegraph/`, `__pycache__/`, `dist/`, `data/`, or `secrets/`.
+
+## Completion expectations
+
+- Run focused tests first, then all applicable standard checks. If a check cannot run, report the
+  exact command and reason.
+- Update `README.md`, `.env.example`, and relevant operational documentation when changing commands,
+  configuration, deployment, recovery behavior, or security assumptions.
+- Summarize behavior changes, validation performed, and any migration, compatibility, or security
+  implications in the final response or pull-request description.

README.md

@@ -4,6 +4,23 @@ Agent CI is a private Gitea webhook host that turns issue and pull-request comme
 OpenCode planning and implementation workflows. Docker Compose runs the webhook worker and a
 private OpenCode server on the same Docker network as Gitea.
 
+## Architecture
+
+The service has one durable execution path:
+
+```text
+webhook -> repository -> reducer -> durable task -> worker -> workflow -> integration
+```
+
+`engine/reducer.py` is the pure job state machine. `engine/repository.py` applies its transitions
+atomically to SQLite and persists the resulting tasks. `application/worker/` executes those tasks
+and passes an explicit `JobRun` into the functions under `workflows/`. Modules under
+`integrations/` own external effects, while `api/` contains the FastAPI host and routes.
+
+Jobs and workflows are immutable snapshots. Workflows return their final comment body directly;
+progress and resource links are emitted as state-machine events through `JobRun`. The `jobs` table
+is the authoritative state snapshot, while `job_events` provides durable idempotency and audit data.
+
 ## Commands
 
 | Location | Command | Behavior |
@@ -15,9 +32,12 @@ private OpenCode server on the same Docker network as Gitea.
 | PR | `/agent iterate [message]` | Resume an agent implementation and its reviewer once. |
 | PR | `/agent fix [message]` | Start a fresh one-shot fix session and push one commit. |
 
-The requester must have Gitea `write`, `admin`, or `owner` permission on the repository. Each
-accepted command gets one Gitea comment, which is updated as the job moves from queued to started
-and then to its final result or failure. Remaining review findings are included in the final update.
+The requester must have Gitea `write`, `admin`, or `owner` permission on the repository. Commands
+are durably sequenced when their webhook arrives, then authorized and executed in receive order per
+issue or pull request. Up to `AGENTCI_MAX_CONCURRENT_JOBS` unrelated targets execute concurrently;
+the default is two. Each command gets one Gitea comment, which is reconciled asynchronously through
+queued, running, and terminal states. Deleted comments are rediscovered by their hidden marker or
+recreated.
 
 ## Deploy
 
@@ -26,26 +46,34 @@ and then to its final result or failure. Remaining review findings are included
    OpenCode models.
 3. Create `secrets/gitea_token`, `secrets/webhook_secret`, and
    `secrets/opencode_server_password`. Use high-entropy values for both secret/password files.
-4. Build the image:
+4. Create the writable state directories for the non-root container user:
 
    ```sh
-   docker compose build
+   mkdir -p data/agentci data/opencode
+   sudo chown -R 10001:10001 data/agentci data/opencode
    ```
 
-5. Authenticate the configured OpenCode providers before starting the persistent server:
+5. Log in to the Gitea container registry with a personal access token, then pull the image:
+
+   ```sh
+   docker login git.krtss.de
+   docker compose pull
+   ```
+
+6. Authenticate the configured OpenCode providers before starting the persistent server:
 
    ```sh
    docker compose run --rm opencode opencode auth login
    docker compose run --rm opencode opencode auth list
    ```
 
-6. Start the services:
+7. Start the services:
 
    ```sh
    docker compose up --no-build -d
    ```
 
-7. In Gitea, create a JSON webhook targeting `http://agentci:8080/webhooks/gitea`. Set the same
+8. In Gitea, create a JSON webhook targeting `http://agentci:8080/webhooks/gitea`. Set the same
    webhook secret and subscribe to issue comments, PR timeline comments, and PR review comments.
 
 OpenCode caches provider state. After adding or changing authentication on an already running
@@ -55,6 +83,22 @@ deployment, run the one-off `auth login` command above and then `docker compose
 healthy and every configured model exists, supports tool calls, accepts its configured variant, and
 has a connected provider. The worker leaves jobs queued while the runtime is unavailable.
 
+### Image publishing
+
+Every push to `main` runs `.gitea/workflows/publish-image.yaml` and publishes the image as both
+`git.krtss.de/stanponomarev/agentci:latest` and
+`git.krtss.de/stanponomarev/agentci:<full-commit-sha>`. Configure these repository Actions secrets
+before the first run:
+
+| Secret | Value |
+| --- | --- |
+| `REGISTRY_USERNAME` | Username that owns the package or can write packages for the owner. |
+| `REGISTRY_TOKEN` | Personal access token with package write permission. |
+
+The automatic Gitea Actions token cannot publish packages. Compose uses `latest` by default; set
+`AGENTCI_IMAGE=git.krtss.de/stanponomarev/agentci:<full-commit-sha>` in `.env` to deploy an immutable
+revision.
+
 ## OpenCode
 
 Models use OpenCode's `provider/model` format. Planning, implementation, and research can use
@@ -64,10 +108,11 @@ configures the research subagent and defaults to `high`. `AGENTCI_EXPLORE_MODEL`
 `AGENTCI_EXPLORE_VARIANT` configure OpenCode's explore agent and default to
 `openai/gpt-5.6-luna` with `low`.
 
-`AGENTCI_OPENCODE_VERSION` controls the npm version or range installed into the image and defaults
-to `^1`. The build verifies that the resolved version is still OpenCode 1.x and prints it. Docker
-may reuse the cached installation layer until the configured version or build inputs change.
-Runtime auto-update is disabled so an image cannot cross into OpenCode 2.x after it is built.
+The `AGENTCI_OPENCODE_VERSION` Docker build argument controls the npm version or range installed into
+the image and defaults to `^1`. The build verifies that the resolved version is still OpenCode 1.x
+and prints it. Docker may reuse the cached installation layer until the configured version or build
+inputs change. Runtime auto-update is disabled so an image cannot cross into OpenCode 2.x after it
+is built.
 
 The trusted configuration is `opencode/opencode.json`. OpenCode's default global and built-in-agent
 permission policies remain in effect; Agent CI does not replace them with an allow-all policy.
@@ -91,10 +136,11 @@ OpenCode permits still has the Unix-level access of that container user, so envi
 is only accidental-exposure hygiene and cannot protect readable files from an allowed shell command.
 
 Docker remains the OS boundary. The services run as non-root without added capabilities,
-privileged mode, an unconfined seccomp/AppArmor profile, or a nested `bubblewrap` sandbox. The only
-host bind mount is the read-only installer directory; there are no
-writable host filesystem mounts. The OpenCode HTTP server is not published to the host, is password
-protected, and is reachable by Agent CI over an internal Compose network.
+privileged mode, an unconfined seccomp/AppArmor profile, or a nested `bubblewrap` sandbox. Persistent
+state is exposed through writable host bind mounts at `./data/agentci` and `./data/opencode`; protect
+these directories because they contain private repository clones, installed tools, provider state,
+and resumable sessions. The OpenCode HTTP server is not published to the host, is password protected,
+and is reachable by Agent CI over an internal Compose network.
 
 ## Development environments
 
@@ -108,13 +154,13 @@ AGENTCI_PYTHON_VERSION=3.13
 AGENTCI_DOTNET_CHANNEL=10.0
 ```
 
-Every name resolves to a file in `install-scripts/`, mounted read-only at
-`/etc/agentci/install-scripts`. Names cannot contain paths and duplicates are rejected. Installers
-run after each implementation clone or branch sync and fail the job on an unknown script, timeout,
-or non-zero exit. They receive no Agent CI or Gitea secret values in their environment, but remain
-trusted operator code. Tools persist under `/var/lib/agentci/dev-tools`, and OpenCode can read or
-modify them through shell commands permitted by its active agent policy. See
-`install-scripts/README.md` for the script contract.
+Every name resolves to a file under `/etc/agentci/install-scripts`, copied from `install-scripts/`
+when the image is built. Rebuild the image after adding, replacing, or removing an installer. Names
+cannot contain paths and duplicates are rejected. Installers run after each implementation clone or
+branch sync and fail the job on an unknown script, timeout, or non-zero exit. They receive no Agent CI
+or Gitea secret values in their environment, but remain trusted operator code. Tools persist under
+`./data/agentci/dev-tools`, and OpenCode can read or modify them through shell commands permitted by
+its active agent policy. See `install-scripts/README.md` for the script contract.
 
 Agent CI continues to create branches, validate diffs, commit, and push after OpenCode returns. This
 keeps workflow behavior deterministic, but an OpenCode agent with shell permission can still run
@@ -122,16 +168,24 @@ Git commands itself.
 
 ## State and recovery
 
-The `agentci_data` volume contains SQLite, workflow clones, and installed development runtimes.
-The `opencode_home` volume contains provider authentication, OpenCode's database, and resumable
+The `data/agentci` directory contains SQLite, workflow clones, and installed development runtimes.
+The `data/opencode` directory contains provider authentication, OpenCode's database, and resumable
 sessions. Tea's Gitea token configuration is regenerated in an ephemeral tmpfs and is not copied to
-`opencode_home`. Back up both persistent volumes together.
+`data/opencode`. Back up both persistent directories together.
+
+SQLite stores the current job state, an idempotent event inbox, and durable listener tasks. State
+transitions and workflow creation/linking commit atomically; timestamps are storage metadata rather
+than reducer state. Control effects retry with bounded backoff. A delayed authorization blocks later
+workflow execution for the same issue or pull request, but not other targets or later control work.
+Development environment installers remain serialized because they share the persistent tools
+directory.
 
 The OpenCode migration tags existing workflows as Codex-owned and preserves their session IDs for
 rollback, but OpenCode refuses to resume them. Follow-up commands against those workflows ask for a
-new plan or implementation. Queued jobs survive restart. An in-progress job is aborted in OpenCode
-and marked failed instead of being replayed because a partial model turn may already have changed
-files. Git pushes are never forced.
+new plan or implementation. Queued jobs survive restart. A restart before `JobStarted` returns the
+task to the queue; after `JobStarted`, the job is failed, its sessions are aborted, and execution is
+never replayed because a partial model turn may already have changed files. Git pushes are never
+forced.
 
 ## Development
 
@@ -142,9 +196,11 @@ uv sync
 uv run ruff check .
 uv run pyright
 uv run pytest
+uv run pytest --cov=agentci --cov-branch
 docker compose config
-docker compose build
 ```
 
-The tests fail if any tracked Python file exceeds 250 lines. Prompts and JSON schemas live outside
-Python so orchestration modules remain small and readable.
+The coverage command is an opt-in diagnostic report; the regular test run remains the default and
+coverage percentage is not used as a pass threshold.
+
+Prompts and JSON schemas live outside Python so orchestration remains focused on execution flow.

compose.yaml

@@ -1,12 +1,6 @@
 services:
   agentci:
-    image: agentci:local
-    build:
-      context: .
-      args:
-        AGENTCI_OPENCODE_VERSION: ${AGENTCI_OPENCODE_VERSION:-^1}
-        CODEGRAPH_VERSION: ${CODEGRAPH_VERSION:-1.3.1}
-        TEA_VERSION: ${TEA_VERSION:-0.14.2}
+    image: ${AGENTCI_IMAGE:-git.krtss.de/stanponomarev/agentci:latest}
     restart: unless-stopped
     depends_on:
       opencode:
@@ -29,6 +23,7 @@ services:
       AGENTCI_PLAN_REVIEW_ROUNDS: ${AGENTCI_PLAN_REVIEW_ROUNDS:-4}
       AGENTCI_IMPLEMENT_REVIEW_ROUNDS: ${AGENTCI_IMPLEMENT_REVIEW_ROUNDS:-3}
       AGENTCI_TURN_TIMEOUT_SECONDS: ${AGENTCI_TURN_TIMEOUT_SECONDS:-3600}
+      AGENTCI_MAX_CONCURRENT_JOBS: ${AGENTCI_MAX_CONCURRENT_JOBS:-2}
       AGENTCI_INSTALL_SCRIPT_TIMEOUT_SECONDS: ${AGENTCI_INSTALL_SCRIPT_TIMEOUT_SECONDS:-900}
       AGENTCI_INSTALL_SCRIPTS: ${AGENTCI_INSTALL_SCRIPTS:-}
       AGENTCI_PYTHON_VERSION: ${AGENTCI_PYTHON_VERSION:-3.13}
@@ -38,8 +33,7 @@ services:
       - webhook_secret
       - opencode_server_password
     volumes:
-      - agentci_data:/var/lib/agentci
-      - ./install-scripts:/etc/agentci/install-scripts:ro
+      - ./data/agentci:/var/lib/agentci
     tmpfs:
       - /run/agentci:mode=1777
     expose:
@@ -49,7 +43,7 @@ services:
       - agentci_control
 
   opencode:
-    image: agentci:local
+    image: ${AGENTCI_IMAGE:-git.krtss.de/stanponomarev/agentci:latest}
     command: ["opencode", "serve", "--hostname", "0.0.0.0", "--port", "4096"]
     restart: unless-stopped
     environment:
@@ -80,8 +74,8 @@ services:
       - gitea_token
       - opencode_server_password
     volumes:
-      - agentci_data:/var/lib/agentci
-      - opencode_home:/var/lib/opencode
+      - ./data/agentci:/var/lib/agentci
+      - ./data/opencode:/var/lib/opencode
     tmpfs:
       - /run/agentci:mode=1777
     expose:
@@ -104,10 +98,6 @@ secrets:
   opencode_server_password:
     file: ./secrets/opencode_server_password
 
-volumes:
-  agentci_data:
-  opencode_home:
-
 networks:
   gitea:
     external: true

install-scripts/README.md

@@ -2,10 +2,10 @@
 
 This directory supplies the ready-made `python` and `dotnet` scripts. They are not reserved:
 modify, replace, or remove them like any other script. Place other trusted executable install
-scripts here and add the desired file names to `AGENTCI_INSTALL_SCRIPTS`. Compose mounts the
-directory read-only at `/etc/agentci/install-scripts`. Executable files run directly; files without
-executable mode run as POSIX shell scripts through `/bin/sh` so bind mounts do not depend on host
-file-mode preservation.
+scripts here and add the desired file names to `AGENTCI_INSTALL_SCRIPTS`. The Docker build copies
+this directory to `/etc/agentci/install-scripts`, so rebuild the image after changing its contents.
+Executable files run directly; files without executable mode run as POSIX shell scripts through
+`/bin/sh`.
 
 Scripts run from the cloned repository with a sanitized environment. They receive:
 
@@ -13,7 +13,7 @@ Scripts run from the cloned repository with a sanitized environment. They receiv
 - `PATH`: `$DEV_TOOLS_DIR/bin` followed by the service path
 - `PYTHON_VERSION` and `DOTNET_CHANNEL`: configured built-in runtime versions
 
-`DEV_TOOLS_DIR` is shared by jobs through the `agentci_data` volume. Put downloaded SDK/runtime
+`DEV_TOOLS_DIR` is shared by jobs through the `data/agentci` bind mount. Put downloaded SDK/runtime
 files beneath it and install command wrappers or symlinks into `$DEV_TOOLS_DIR/bin`; that `bin`
 directory is prepended to implementation agents' `PATH`. Environment changes made by a script do
 not persist into implementation turns.

pyproject.toml

@@ -20,7 +20,7 @@ dev = [
   "pyright>=1.1.403",
   "pytest>=8.4,<9",
   "pytest-asyncio>=1.1,<2",
-  "respx>=0.22,<1",
+  "pytest-cov>=6,<8",
   "ruff>=0.12,<1",
 ]
 

src/agentci/__init__.py

@@ -1,3 +1 @@
 """Gitea-triggered OpenCode workflow host."""
-
-__version__ = "0.1.0"

src/agentci/__main__.py

@@ -2,8 +2,8 @@ from __future__ import annotations
 
 import uvicorn
 
-from agentci.app import create_app
-from agentci.config import Settings
+from agentci.api.app import create_app
+from agentci.config.settings import Settings
 
 
 def main() -> None:
@@ -19,4 +19,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-

src/agentci/adapters/__init__.py

@@ -1,2 +0,0 @@
-"""External-system adapters."""
-

src/agentci/adapters/database.py

@@ -1,75 +0,0 @@
-from __future__ import annotations
-
-import logging
-import sqlite3
-from collections.abc import Callable
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import TypeVar
-
-T = TypeVar("T")
-log = logging.getLogger(__name__)
-
-
-def now() -> str:
-    return datetime.now(UTC).isoformat()
-
-
-class Database:
-    def __init__(self, database_path: Path, migrations_dir: Path) -> None:
-        self.database_path = database_path
-        self.migrations_dir = migrations_dir
-
-    async def initialize(self) -> None:
-        log.info("database initialization started", extra={"operation": "database.initialize"})
-        self.database_path.parent.mkdir(parents=True, exist_ok=True)
-        try:
-            await self._run(self._initialize_sync)
-        except Exception:
-            log.exception(
-                "database initialization failed", extra={"operation": "database.initialize"}
-            )
-            raise
-        log.info("database initialization completed", extra={"operation": "database.initialize"})
-
-    def _connect(self) -> sqlite3.Connection:
-        connection = sqlite3.connect(self.database_path, timeout=30)
-        connection.row_factory = sqlite3.Row
-        connection.execute("PRAGMA journal_mode=WAL")
-        connection.execute("PRAGMA foreign_keys=ON")
-        return connection
-
-    def _initialize_sync(self, connection: sqlite3.Connection) -> None:
-        connection.execute(
-            "CREATE TABLE IF NOT EXISTS schema_migrations "
-            "(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)"
-        )
-        applied = {
-            row[0] for row in connection.execute("SELECT version FROM schema_migrations")
-        }
-        for path in sorted(self.migrations_dir.glob("*.sql")):
-            version = int(path.name.split("_", 1)[0])
-            if version in applied:
-                continue
-            connection.executescript(path.read_text())
-            connection.execute(
-                "INSERT OR IGNORE INTO schema_migrations VALUES (?, ?)",
-                (version, now()),
-            )
-
-    async def _update(self, table: str, row_id: str, updates: dict[str, object]) -> None:
-        if not updates:
-            return
-        columns = ", ".join(f"{column}=?" for column in updates)
-        values = [*updates.values(), row_id]
-        await self._run(
-            lambda connection: connection.execute(
-                f"UPDATE {table} SET {columns} WHERE id=?", values
-            )
-        )
-
-    async def _run(self, operation: Callable[[sqlite3.Connection], T]) -> T:
-        # Operations are deliberately tiny and serialized by the single worker.
-        # Avoid a thread pool so SQLite transactions retain deterministic ordering.
-        with self._connect() as connection:
-            return operation(connection)

src/agentci/adapters/job_store.py

@@ -1,200 +0,0 @@
-from __future__ import annotations
-
-import logging
-import sqlite3
-
-from agentci.adapters.database import Database, now
-from agentci.domain.models import Job, JobKind, JobStatus
-
-log = logging.getLogger(__name__)
-
-
-class JobStore(Database):
-    async def record_delivery(self, delivery_id: str, comment_id: int) -> bool:
-        def record(connection: sqlite3.Connection) -> bool:
-            try:
-                connection.execute(
-                    "INSERT INTO deliveries VALUES (?, ?, ?)",
-                    (delivery_id, comment_id, now()),
-                )
-            except sqlite3.IntegrityError:
-                return False
-            return True
-
-        return await self._run(record)
-
-    async def enqueue(self, delivery_id: str, job: Job) -> bool:
-        return await self._run(lambda connection: self._enqueue(connection, delivery_id, job))
-
-    @staticmethod
-    def _enqueue(connection: sqlite3.Connection, delivery_id: str, job: Job) -> bool:
-        try:
-            with connection:
-                connection.execute(
-                    "INSERT INTO deliveries VALUES (?, ?, ?)",
-                    (delivery_id, job.comment_id, now()),
-                )
-                connection.execute(
-                    """
-                    INSERT INTO jobs (
-                        id, kind, target_key, repo_owner, repo_name, issue_number,
-                        pr_number, requester, message, comment_id, workflow_id,
-                        status, stage, runtime_session_id, created_at
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    """,
-                    (
-                        job.id,
-                        job.kind,
-                        job.target_key,
-                        job.repo_owner,
-                        job.repo_name,
-                        job.issue_number,
-                        job.pr_number,
-                        job.requester,
-                        job.message,
-                        job.comment_id,
-                        job.workflow_id,
-                        job.status,
-                        job.stage,
-                        job.runtime_session_id,
-                        now(),
-                    ),
-                )
-        except sqlite3.IntegrityError:
-            return False
-        return True
-
-    async def claim_next(self) -> Job | None:
-        return await self._run(self._claim_next)
-
-    @staticmethod
-    def _claim_next(connection: sqlite3.Connection) -> Job | None:
-        connection.execute("BEGIN IMMEDIATE")
-        row = connection.execute(
-            "SELECT * FROM jobs WHERE status = ? ORDER BY created_at LIMIT 1",
-            (JobStatus.QUEUED,),
-        ).fetchone()
-        if row is None:
-            connection.commit()
-            return None
-        connection.execute(
-            "UPDATE jobs SET status = ?, stage = ?, started_at = ? WHERE id = ?",
-            (JobStatus.RUNNING, "starting", now(), row["id"]),
-        )
-        connection.commit()
-        return job_from_row(row, status=JobStatus.RUNNING, stage="starting")
-
-    async def update_job(
-        self,
-        job_id: str,
-        *,
-        status: JobStatus | None = None,
-        stage: str | None = None,
-        error: str | None = None,
-        workflow_id: str | None = None,
-        runtime_session_id: str | None = None,
-    ) -> None:
-        updates: dict[str, object] = {}
-        if status is not None:
-            updates["status"] = status
-            if status in {JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.REJECTED}:
-                updates["finished_at"] = now()
-        if stage is not None:
-            updates["stage"] = stage
-        if error is not None:
-            updates["error"] = error
-        if workflow_id is not None:
-            updates["workflow_id"] = workflow_id
-        if runtime_session_id is not None:
-            updates["runtime_session_id"] = runtime_session_id
-        await self._update("jobs", job_id, updates)
-        log.info(
-            "job state updated",
-            extra={
-                "operation": "job.update",
-                "job_id": job_id,
-                "workflow_id": workflow_id,
-                "stage": stage,
-                "status_code": status.value if status is not None else None,
-            },
-        )
-
-    async def set_job_comment(self, job_id: str, column: str, comment_id: int) -> None:
-        if column not in {"accepted_comment_id", "started_comment_id"}:
-            raise ValueError("Unsupported comment column")
-        await self._run(
-            lambda connection: connection.execute(
-                f"UPDATE jobs SET {column} = ? WHERE id = ?", (comment_id, job_id)
-            )
-        )
-
-    async def job_stage(self, job_id: str) -> str:
-        def select(connection: sqlite3.Connection) -> str:
-            row = connection.execute("SELECT stage FROM jobs WHERE id=?", (job_id,)).fetchone()
-            return str(row["stage"]) if row else "unknown"
-
-        return await self._run(select)
-
-    async def operational_comment_ids(self, owner: str, repo: str, issue: int) -> set[int]:
-        return await self._run(
-            lambda connection: {
-                value
-                for row in connection.execute(
-                    """
-                    SELECT accepted_comment_id, started_comment_id FROM jobs
-                    WHERE repo_owner=? AND repo_name=? AND issue_number=?
-                    """,
-                    (owner, repo, issue),
-                )
-                for value in row
-                if value is not None
-            }
-        )
-
-    async def recover_running(self) -> list[Job]:
-        def recover(connection: sqlite3.Connection) -> list[Job]:
-            rows = connection.execute(
-                "SELECT * FROM jobs WHERE status=?", (JobStatus.RUNNING,)
-            ).fetchall()
-            with connection:
-                connection.execute(
-                    """
-                    UPDATE jobs SET status=?, stage=?, error=?, finished_at=?
-                    WHERE status=?
-                    """,
-                    (
-                        JobStatus.FAILED,
-                        "interrupted",
-                        "Service restarted during an active OpenCode turn",
-                        now(),
-                        JobStatus.RUNNING,
-                    ),
-                )
-            return [job_from_row(row) for row in rows]
-
-        return await self._run(recover)
-
-
-def job_from_row(
-    row: sqlite3.Row,
-    *,
-    status: JobStatus | None = None,
-    stage: str | None = None,
-) -> Job:
-    return Job(
-        id=row["id"],
-        kind=JobKind(row["kind"]),
-        target_key=row["target_key"],
-        repo_owner=row["repo_owner"],
-        repo_name=row["repo_name"],
-        issue_number=row["issue_number"],
-        pr_number=row["pr_number"],
-        requester=row["requester"],
-        message=row["message"],
-        comment_id=row["comment_id"],
-        workflow_id=row["workflow_id"],
-        status=status or JobStatus(row["status"]),
-        stage=stage or row["stage"],
-        accepted_comment_id=row["accepted_comment_id"],
-        runtime_session_id=row["runtime_session_id"],
-    )

src/agentci/adapters/opencode_support.py

@@ -1,77 +0,0 @@
-import json
-from pathlib import Path
-from time import monotonic
-from typing import Any
-
-
-def model_parts(model: str) -> tuple[str, str]:
-    provider, separator, model_id = model.partition("/")
-    if not separator or not provider or not model_id:
-        raise ValueError(f"OpenCode model must use provider/model format: {model}")
-    return provider, model_id
-
-
-def error_message(error: object) -> str | None:
-    if not error:
-        return None
-    if isinstance(error, dict):
-        return str(error.get("name") or error.get("message") or error)
-    return str(error)
-
-
-def elapsed_ms(started: float) -> int:
-    return round((monotonic() - started) * 1000)
-
-
-def directory_headers(workspace: Path) -> dict[str, str]:
-    return {"X-Opencode-Directory": str(workspace.resolve())}
-
-
-def load_schema(schemas_dir: Path, name: str) -> dict[str, Any]:
-    try:
-        value = json.loads((schemas_dir / name).read_text())
-    except (OSError, ValueError) as exc:
-        raise ValueError(f"Cannot load result schema {name}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise ValueError(f"Result schema {name} is not a JSON object")
-    return value
-
-
-def api_contract_ready(document: object) -> bool:
-    if not isinstance(document, dict) or not isinstance(document.get("paths"), dict):
-        return False
-    paths = document["paths"]
-    fixed = {"/global/health": "get", "/provider": "get", "/session": "post"}
-    if any(method not in paths.get(path, {}) for path, method in fixed.items()):
-        return False
-    session_paths = [path for path in paths if path.startswith("/session/{")]
-    has_message = any(
-        path.endswith("/message") and "post" in paths[path] for path in session_paths
-    )
-    has_abort = any(path.endswith("/abort") and "post" in paths[path] for path in session_paths)
-    return has_message and has_abort
-
-
-def models_ready(
-    payload: object, requirements: set[tuple[str, str, str | None]]
-) -> bool:
-    if not isinstance(payload, dict):
-        return False
-    connected = set(payload.get("connected", []))
-    providers = {
-        item.get("id"): item
-        for item in payload.get("all", [])
-        if isinstance(item, dict) and isinstance(item.get("models"), dict)
-    }
-    for provider_id, model_id, variant in requirements:
-        provider = providers.get(provider_id)
-        if provider_id not in connected or not isinstance(provider, dict):
-            return False
-        model: Any = provider["models"].get(model_id)
-        if not isinstance(model, dict) or model.get("status") == "deprecated":
-            return False
-        if model.get("capabilities", {}).get("toolcall") is not True:
-            return False
-        if variant and variant not in model.get("variants", {}):
-            return False
-    return True

src/agentci/adapters/storage.py

@@ -1,7 +0,0 @@
-from agentci.adapters.job_store import JobStore
-from agentci.adapters.workflow_store import WorkflowStore
-
-
-class Storage(JobStore, WorkflowStore):
-    """Combined durable job and workflow repository."""
-

src/agentci/adapters/workflow_store.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import sqlite3
-from pathlib import Path
-
-from agentci.adapters.database import Database, now
-from agentci.domain.models import Workflow, WorkflowKind, WorkflowStatus
-
-
-class WorkflowStore(Database):
-    async def get_workflow(self, workflow_id: str) -> Workflow | None:
-        return await self._run(
-            lambda connection: workflow_from_row(
-                connection.execute(
-                    "SELECT * FROM workflows WHERE id=?", (workflow_id,)
-                ).fetchone()
-            )
-        )
-
-    async def create_workflow(self, workflow: Workflow) -> None:
-        timestamp = now()
-        await self._run(
-            lambda connection: connection.execute(
-                """
-                INSERT INTO workflows (
-                    id, kind, repo_owner, repo_name, issue_number, pr_number,
-                    base_sha, branch, workspace_path, primary_session_id,
-                    reviewer_session_id, artifact, review_json, status, runtime,
-                    created_at, updated_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    workflow.id,
-                    workflow.kind,
-                    workflow.repo_owner,
-                    workflow.repo_name,
-                    workflow.issue_number,
-                    workflow.pr_number,
-                    workflow.base_sha,
-                    workflow.branch,
-                    str(workflow.workspace_path),
-                    workflow.primary_session_id,
-                    workflow.reviewer_session_id,
-                    workflow.artifact,
-                    workflow.review_json,
-                    workflow.status,
-                    workflow.runtime,
-                    timestamp,
-                    timestamp,
-                ),
-            )
-        )
-
-    async def update_workflow(self, workflow: Workflow) -> None:
-        await self._update(
-            "workflows",
-            workflow.id,
-            {
-                "pr_number": workflow.pr_number,
-                "branch": workflow.branch,
-                "primary_session_id": workflow.primary_session_id,
-                "reviewer_session_id": workflow.reviewer_session_id,
-                "artifact": workflow.artifact,
-                "review_json": workflow.review_json,
-                "status": workflow.status,
-                "updated_at": now(),
-            },
-        )
-
-    async def latest_workflow(
-        self,
-        owner: str,
-        repo: str,
-        issue: int,
-        kind: WorkflowKind,
-    ) -> Workflow | None:
-        return await self._run(
-            lambda connection: workflow_from_row(
-                connection.execute(
-                    """
-                    SELECT * FROM workflows
-                    WHERE repo_owner=? AND repo_name=? AND issue_number=?
-                      AND kind=? AND status=?
-                    ORDER BY created_at DESC LIMIT 1
-                    """,
-                    (owner, repo, issue, kind, WorkflowStatus.COMPLETED),
-                ).fetchone()
-            )
-        )
-
-    async def workflow_for_pr(self, owner: str, repo: str, pr: int) -> Workflow | None:
-        return await self._run(
-            lambda connection: workflow_from_row(
-                connection.execute(
-                    """
-                    SELECT * FROM workflows
-                    WHERE repo_owner=? AND repo_name=? AND pr_number=? AND kind=?
-                    ORDER BY created_at DESC LIMIT 1
-                    """,
-                    (owner, repo, pr, WorkflowKind.IMPLEMENT),
-                ).fetchone()
-            )
-        )
-
-    async def implementation_workflows(
-        self, owner: str, repo: str, issue: int
-    ) -> list[Workflow]:
-        return await self._run(
-            lambda connection: [
-                item
-                for row in connection.execute(
-                    """
-                    SELECT * FROM workflows
-                    WHERE repo_owner=? AND repo_name=? AND issue_number=? AND kind=?
-                      AND pr_number IS NOT NULL
-                    ORDER BY created_at DESC
-                    """,
-                    (owner, repo, issue, WorkflowKind.IMPLEMENT),
-                )
-                if (item := workflow_from_row(row)) is not None
-            ]
-        )
-
-    async def fail_job_workflow(self, job_id: str) -> None:
-        await self._run(
-            lambda connection: connection.execute(
-                """
-                UPDATE workflows SET status=?, updated_at=?
-                WHERE id=(SELECT workflow_id FROM jobs WHERE id=?)
-                  AND status=?
-                """,
-                (WorkflowStatus.FAILED, now(), job_id, WorkflowStatus.ACTIVE),
-            )
-        )
-
-
-def workflow_from_row(row: sqlite3.Row | None) -> Workflow | None:
-    if row is None:
-        return None
-    return Workflow(
-        id=row["id"],
-        kind=WorkflowKind(row["kind"]),
-        repo_owner=row["repo_owner"],
-        repo_name=row["repo_name"],
-        issue_number=row["issue_number"],
-        pr_number=row["pr_number"],
-        base_sha=row["base_sha"],
-        runtime=row["runtime"],
-        branch=row["branch"],
-        workspace_path=Path(row["workspace_path"]),
-        primary_session_id=row["primary_session_id"],
-        reviewer_session_id=row["reviewer_session_id"],
-        artifact=row["artifact"],
-        review_json=row["review_json"],
-        status=WorkflowStatus(row["status"]),
-    )

src/agentci/api/__init__.py

@@ -1,2 +1 @@
-"""HTTP API."""
-
+"""HTTP application and routes."""

src/agentci/api/app.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from agentci.api.errors import register_error_handlers
+from agentci.api.lifespan import create_lifespan
+from agentci.api.routes.health import router as health_router
+from agentci.api.routes.webhook import router as webhook_router
+from agentci.config.settings import Settings
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    selected_settings = settings or Settings()
+    app = FastAPI(
+        title="Agent CI",
+        version="0.1.0",
+        lifespan=create_lifespan(selected_settings),
+    )
+    app.include_router(health_router)
+    app.include_router(webhook_router)
+    register_error_handlers(app)
+    return app
+
+
+app = create_app()

src/agentci/api/dependencies.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+
+from agentci.application.runtime import Runtime
+
+
+def get_runtime(request: Request) -> Runtime:
+    return request.app.state.runtime
+
+
+type RuntimeDependency = Annotated[Runtime, Depends(get_runtime)]

src/agentci/api/errors.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+log = logging.getLogger(__name__)
+
+
+async def unhandled_error(request: Request, exc: Exception) -> JSONResponse:
+    log.exception(
+        "unhandled HTTP request failure",
+        extra={
+            "operation": "http.request",
+            "method": request.method,
+            "path": request.url.path,
+            "error_message": str(exc),
+            "status_code": 500,
+        },
+    )
+    return JSONResponse(
+        status_code=500,
+        content={"detail": "Internal server error. See service logs for diagnostics."},
+    )
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    app.exception_handler(Exception)(unhandled_error)

src/agentci/api/lifespan.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
+
+from fastapi import FastAPI
+
+from agentci.application.runtime import build_runtime
+from agentci.config.settings import Settings
+from agentci.observability.logging import configure_logging
+
+log = logging.getLogger(__name__)
+Lifespan = Callable[[FastAPI], AbstractAsyncContextManager[None]]
+
+
+def create_lifespan(settings: Settings) -> Lifespan:
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+        configure_logging()
+        log.info("service startup started", extra={"operation": "service.startup"})
+        try:
+            runtime = await build_runtime(settings)
+        except Exception:
+            log.exception("service startup failed", extra={"operation": "service.startup"})
+            raise
+        app.state.runtime = runtime
+        stop = asyncio.Event()
+        worker_task = asyncio.create_task(runtime.worker.run(stop), name="agentci-worker")
+        try:
+            log.info("service startup completed", extra={"operation": "service.startup"})
+            yield
+        finally:
+            log.info("service shutdown started", extra={"operation": "service.shutdown"})
+            stop.set()
+            worker_task.cancel()
+            try:
+                with suppress(asyncio.CancelledError):
+                    await worker_task
+            finally:
+                await runtime.close()
+            log.info("service shutdown completed", extra={"operation": "service.shutdown"})
+
+    return lifespan

src/agentci/api/routes/__init__.py

@@ -0,0 +1 @@
+"""FastAPI route modules."""

src/agentci/api/routes/health.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Request, Response, status
+from fastapi import APIRouter, Response, status
+
+from agentci.api.dependencies import RuntimeDependency
 
 router = APIRouter()
 
@@ -11,8 +13,8 @@ async def live() -> dict[str, str]:
 
 
 @router.get("/health/ready")
-async def ready(request: Request, response: Response) -> dict[str, str]:
-    if not await request.app.state.container.opencode.ready():
+async def ready(runtime: RuntimeDependency, response: Response) -> dict[str, str]:
+    if not await runtime.opencode.ready():
         response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
         return {"status": "not-ready", "reason": "opencode provider is not connected"}
     return {"status": "ready"}

src/agentci/api/routes/webhook.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi import APIRouter, HTTPException, Request, Response, status
+
+from agentci.api.dependencies import RuntimeDependency
+from agentci.application.runtime import Runtime
+from agentci.engine.model import IncomingCommand
+from agentci.integrations.gitea.webhooks import (
+    SUPPORTED_EVENTS,
+    incoming_command_from_payload,
+    valid_signature,
+)
+
+router = APIRouter()
+log = logging.getLogger(__name__)
+
+
+@router.post("/webhooks/gitea")
+async def webhook(request: Request, runtime: RuntimeDependency) -> Response:
+    body = await request.body()
+    signature = request.headers.get("X-Gitea-Signature", "")
+    if not valid_signature(runtime.settings.webhook_secret, body, signature):
+        log.warning(
+            "webhook signature rejected",
+            extra={"operation": "webhook.verify", "path": request.url.path},
+        )
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid webhook signature")
+    event_name = request.headers.get("X-Gitea-Event-Type") or request.headers.get(
+        "X-Gitea-Event", ""
+    )
+    if event_name not in SUPPORTED_EVENTS:
+        log.info(
+            "unsupported webhook ignored",
+            extra={"operation": "webhook.filter", "stage": event_name or "missing"},
+        )
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+    try:
+        payload = json.loads(body)
+        if not isinstance(payload, dict):
+            raise ValueError("Webhook payload must be a JSON object")
+        event = incoming_command_from_payload(
+            request.headers.get("X-Gitea-Delivery", ""),
+            payload,
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        log.warning(
+            "webhook payload rejected",
+            extra={"operation": "webhook.parse", "stage": event_name},
+            exc_info=exc,
+        )
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Invalid webhook payload") from exc
+    if event is None or event.requester.casefold() == runtime.settings.bot_username.casefold():
+        log.info("webhook ignored", extra={"operation": "webhook.filter", "stage": event_name})
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+    return await _handle_command(runtime, event)
+
+
+async def _handle_command(runtime: Runtime, event: IncomingCommand) -> Response:
+    extra = {"operation": "command.handle", "target": event.target_key}
+    if not event.body.strip().startswith("/agent"):
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+    if not event.delivery_id:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Missing X-Gitea-Delivery")
+    log.info("agent command received", extra=extra)
+    try:
+        result = await runtime.repository.accept(event)
+    except Exception:
+        log.exception("could not persist command", extra=extra)
+        raise
+    if result.duplicate:
+        log.info("duplicate command ignored", extra={**extra, "job_id": result.job.id})
+        return Response(status_code=status.HTTP_200_OK)
+    log.info(
+        "agent command persisted",
+        extra={
+            **extra,
+            "job_id": result.job.id,
+            "receive_sequence": result.job.receive_sequence,
+        },
+    )
+    return Response(status_code=status.HTTP_202_ACCEPTED)

src/agentci/api/webhook.py

@@ -1,160 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import hmac
-import json
-import logging
-from typing import Any
-from uuid import uuid4
-
-from fastapi import APIRouter, HTTPException, Request, Response, status
-
-from agentci.domain.commands import CommandError, parse_command, resolve_job_kind
-from agentci.domain.models import CommandEvent, Job, JobStatus
-
-router = APIRouter()
-log = logging.getLogger(__name__)
-SUPPORTED_EVENTS = {
-    "issue_comment",
-    "pull_request_comment",
-    "pull_request_review_comment",
-}
-
-
-@router.post("/webhooks/gitea")
-async def webhook(request: Request) -> Response:
-    container = request.app.state.container
-    body = await request.body()
-    signature = request.headers.get("X-Gitea-Signature", "")
-    if not valid_signature(container.settings.webhook_secret, body, signature):
-        log.warning(
-            "webhook signature rejected",
-            extra={"operation": "webhook.verify", "path": request.url.path},
-        )
-        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid webhook signature")
-    event_name = request.headers.get("X-Gitea-Event-Type") or request.headers.get(
-        "X-Gitea-Event", ""
-    )
-    if event_name not in SUPPORTED_EVENTS:
-        log.info(
-            "unsupported webhook ignored",
-            extra={"operation": "webhook.filter", "stage": event_name or "missing"},
-        )
-        return Response(status_code=status.HTTP_204_NO_CONTENT)
-    try:
-        payload = json.loads(body)
-        event = _event_from_payload(
-            request.headers.get("X-Gitea-Delivery", ""),
-            payload,
-        )
-    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
-        log.warning(
-            "webhook payload rejected",
-            extra={"operation": "webhook.parse", "stage": event_name},
-            exc_info=exc,
-        )
-        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Invalid webhook payload") from exc
-    if event is None or event.requester == container.settings.bot_username:
-        log.info("webhook ignored", extra={"operation": "webhook.filter", "stage": event_name})
-        return Response(status_code=status.HTTP_204_NO_CONTENT)
-    return await _handle_command(container, event)
-
-
-def valid_signature(secret: bytes, body: bytes, signature: str) -> bool:
-    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
-    return bool(signature) and hmac.compare_digest(expected, signature)
-
-
-async def _handle_command(container: Any, event: CommandEvent) -> Response:
-    extra = {"operation": "command.handle", "target": event.target_key}
-    if not event.body.strip().startswith("/agent"):
-        return Response(status_code=status.HTTP_204_NO_CONTENT)
-    log.info("agent command received", extra=extra)
-    permitted = await container.gitea.has_write_permission(
-        event.repo_owner, event.repo_name, event.requester
-    )
-    if not permitted:
-        log.warning("agent command rejected: insufficient permission", extra=extra)
-        if await container.storage.record_delivery(event.delivery_id, event.comment_id):
-            await container.gitea.create_comment(
-                event.repo_owner,
-                event.repo_name,
-                event.issue_number,
-                "Agent command rejected: repository write permission is required.",
-            )
-        return Response(status_code=status.HTTP_202_ACCEPTED)
-    try:
-        command = parse_command(event.body)
-    except CommandError as exc:
-        log.info("agent command rejected: invalid syntax", extra=extra)
-        if await container.storage.record_delivery(event.delivery_id, event.comment_id):
-            await container.gitea.create_comment(
-                event.repo_owner, event.repo_name, event.issue_number, str(exc)
-            )
-        return Response(status_code=status.HTTP_202_ACCEPTED)
-    if command is None:
-        return Response(status_code=status.HTTP_204_NO_CONTENT)
-    try:
-        kind = resolve_job_kind(command, is_pull_request=event.is_pull_request)
-    except CommandError as exc:
-        log.info("agent command rejected: invalid target", extra=extra)
-        if await container.storage.record_delivery(event.delivery_id, event.comment_id):
-            await container.gitea.create_comment(
-                event.repo_owner, event.repo_name, event.issue_number, str(exc)
-            )
-        return Response(status_code=status.HTTP_202_ACCEPTED)
-    job = Job(
-        id=str(uuid4()),
-        kind=kind,
-        target_key=event.target_key,
-        repo_owner=event.repo_owner,
-        repo_name=event.repo_name,
-        issue_number=event.issue_number,
-        pr_number=event.pr_number,
-        requester=event.requester,
-        message=command.message,
-        comment_id=event.comment_id,
-        status=JobStatus.QUEUED,
-        stage="queued",
-    )
-    if not await container.storage.enqueue(event.delivery_id, job):
-        log.info("duplicate command ignored", extra={**extra, "job_id": job.id})
-        return Response(status_code=status.HTTP_200_OK)
-    log.info(
-        "agent job queued",
-        extra={**extra, "job_id": job.id, "stage": job.kind.value},
-    )
-    comment_id = await container.gitea.create_comment(
-        event.repo_owner,
-        event.repo_name,
-        event.issue_number,
-        f"Agent job `{job.id}` queued (`{job.kind}`).",
-    )
-    await container.storage.set_job_comment(job.id, "accepted_comment_id", comment_id)
-    return Response(status_code=status.HTTP_202_ACCEPTED)
-
-
-def _event_from_payload(delivery_id: str, payload: dict[str, Any]) -> CommandEvent | None:
-    if payload.get("action") != "created":
-        return None
-    comment = payload["comment"]
-    repository = payload["repository"]
-    owner = repository["owner"]
-    owner_name = owner.get("login") or owner.get("username") or owner["name"]
-    pull = payload.get("pull_request")
-    is_pull = bool(payload.get("is_pull") or pull)
-    issue = payload.get("issue")
-    target = pull or issue
-    if target is None:
-        raise ValueError("Comment payload has no issue or pull request")
-    number = int(target["number"])
-    return CommandEvent(
-        delivery_id=delivery_id,
-        comment_id=int(comment["id"]),
-        repo_owner=owner_name,
-        repo_name=repository["name"],
-        issue_number=number,
-        pr_number=number if is_pull else None,
-        requester=comment["user"]["login"],
-        body=comment.get("body") or "",
-    )

src/agentci/app.py

@@ -1,71 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager, suppress
-
-from fastapi import FastAPI, Request
-from fastapi.responses import JSONResponse
-
-from agentci.api.health import router as health_router
-from agentci.api.webhook import router as webhook_router
-from agentci.config import Settings
-from agentci.container import build_container
-from agentci.logging import configure_logging
-
-log = logging.getLogger(__name__)
-
-def create_app(settings: Settings | None = None) -> FastAPI:
-    selected_settings = settings or Settings()
-
-    @asynccontextmanager
-    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
-        configure_logging()
-        log.info("service startup started", extra={"operation": "service.startup"})
-        try:
-            container = await build_container(selected_settings)
-        except Exception:
-            log.exception("service startup failed", extra={"operation": "service.startup"})
-            raise
-        app.state.container = container
-        stop = asyncio.Event()
-        worker_task = asyncio.create_task(container.worker.run(stop), name="agentci-worker")
-        try:
-            log.info("service startup completed", extra={"operation": "service.startup"})
-            yield
-        finally:
-            log.info("service shutdown started", extra={"operation": "service.shutdown"})
-            stop.set()
-            worker_task.cancel()
-            try:
-                with suppress(asyncio.CancelledError):
-                    await worker_task
-            finally:
-                await container.close()
-            log.info("service shutdown completed", extra={"operation": "service.shutdown"})
-
-    app = FastAPI(title="Agent CI", version="0.1.0", lifespan=lifespan)
-    app.include_router(health_router)
-    app.include_router(webhook_router)
-
-    @app.exception_handler(Exception)
-    async def unhandled_error(request: Request, exc: Exception) -> JSONResponse:
-        log.exception(
-            "unhandled HTTP request failure",
-            extra={
-                "operation": "http.request",
-                "method": request.method,
-                "path": request.url.path,
-                "status_code": 500,
-            },
-        )
-        return JSONResponse(
-            status_code=500,
-            content={"detail": "Internal server error. See service logs for diagnostics."},
-        )
-
-    return app
-
-
-app = create_app()

src/agentci/application/__init__.py

@@ -0,0 +1 @@
+"""Application composition and durable orchestration."""

src/agentci/application/runtime.py

@@ -2,47 +2,45 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass
-from pathlib import Path
 
-from agentci.adapters.development import DevelopmentEnvironment
-from agentci.adapters.git import GitClient
-from agentci.adapters.gitea import GiteaClient
-from agentci.adapters.opencode import OpenCodeClient
-from agentci.adapters.storage import Storage
-from agentci.config import Settings
-from agentci.prompts import PromptLibrary
-from agentci.worker import Worker
-from agentci.workflows.common import Dependencies
-from agentci.workflows.context import ContextBuilder
-from agentci.workflows.dispatcher import Dispatcher
+from agentci.application.worker.runner import Worker
+from agentci.config.settings import Settings
+from agentci.engine.repository import Repository
+from agentci.integrations.development import DevelopmentEnvironment
+from agentci.integrations.git import Git
+from agentci.integrations.gitea.client import Gitea
+from agentci.integrations.opencode.client import OpenCode
+from agentci.prompts.library import PromptLibrary
+from agentci.workflows.services import WorkflowServices
 
 log = logging.getLogger(__name__)
 
 @dataclass(frozen=True)
-class Container:
+class Runtime:
     settings: Settings
-    storage: Storage
-    gitea: GiteaClient
-    git: GitClient
-    opencode: OpenCodeClient
+    repository: Repository
+    gitea: Gitea
+    git: Git
+    opencode: OpenCode
     worker: Worker
 
     async def close(self) -> None:
-        log.info("container shutdown started", extra={"operation": "container.close"})
-        await self.opencode.close()
-        await self.gitea.close()
-        log.info("container shutdown completed", extra={"operation": "container.close"})
+        log.info("runtime shutdown started", extra={"operation": "runtime.close"})
+        try:
+            await self.opencode.close()
+        finally:
+            await self.gitea.close()
+        log.info("runtime shutdown completed", extra={"operation": "runtime.close"})
 
 
-async def build_container(settings: Settings) -> Container:
-    log.info("container initialization started", extra={"operation": "container.build"})
-    package_dir = Path(__file__).parent
+async def build_runtime(settings: Settings) -> Runtime:
+    log.info("runtime initialization started", extra={"operation": "runtime.build"})
     settings.data_dir.mkdir(parents=True, exist_ok=True)
     settings.workspaces_dir.mkdir(parents=True, exist_ok=True)
-    storage = Storage(settings.database_path, package_dir / "migrations")
-    await storage.initialize()
-    gitea = GiteaClient(settings.gitea_url, settings.gitea_token)
-    git = GitClient(
+    repository = Repository(settings.database_path)
+    await repository.initialize()
+    gitea = Gitea(settings.gitea_url, settings.gitea_token)
+    git = Git(
         gitea_url=settings.gitea_url,
         username=settings.bot_username,
         token=settings.gitea_token,
@@ -50,11 +48,12 @@ async def build_container(settings: Settings) -> Container:
         commit_name=settings.bot_name,
         commit_email=settings.bot_email,
     )
-    opencode = OpenCodeClient(
+    prompts = PromptLibrary()
+    opencode = OpenCode(
         base_url=settings.opencode_url,
         username=settings.opencode_server_username,
         password=settings.opencode_server_password,
-        schemas_dir=package_dir / "prompts" / "schemas",
+        schemas_dir=prompts.schemas_dir,
         health_directory=settings.workspaces_dir,
         required_models=(
             (settings.plan_model, settings.plan_variant),
@@ -64,8 +63,6 @@ async def build_container(settings: Settings) -> Container:
         ),
         timeout_seconds=settings.turn_timeout_seconds,
     )
-    prompts = PromptLibrary()
-    context = ContextBuilder(gitea, storage)
     development = DevelopmentEnvironment(
         scripts=settings.install_scripts,
         scripts_dir=settings.install_scripts_dir,
@@ -74,25 +71,25 @@ async def build_container(settings: Settings) -> Container:
         python_version=settings.python_version,
         dotnet_channel=settings.dotnet_channel,
     )
-    dependencies = Dependencies(
+    services = WorkflowServices(
         settings=settings,
-        storage=storage,
+        repository=repository,
         gitea=gitea,
         git=git,
         opencode=opencode,
         prompts=prompts,
-        context=context,
         development=development,
     )
-    dispatcher = Dispatcher(dependencies)
     worker = Worker(
-        storage=storage,
+        repository=repository,
         gitea=gitea,
         opencode=opencode,
-        dispatcher=dispatcher,
+        services=services,
         poll_seconds=settings.worker_poll_seconds,
+        max_concurrent_jobs=settings.max_concurrent_jobs,
         workspaces_dir=settings.workspaces_dir,
+        bot_username=settings.bot_username,
     )
-    container = Container(settings, storage, gitea, git, opencode, worker)
-    log.info("container initialization completed", extra={"operation": "container.build"})
-    return container
+    runtime = Runtime(settings, repository, gitea, git, opencode, worker)
+    log.info("runtime initialization completed", extra={"operation": "runtime.build"})
+    return runtime

src/agentci/application/worker/__init__.py

@@ -0,0 +1 @@
+"""Durable task runner and task handlers."""

src/agentci/application/worker/authorization.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from agentci.engine.events import PermissionDenied, PermissionGranted
+from agentci.engine.model import Job, JobStatus, Task
+from agentci.engine.repository import Repository
+from agentci.integrations.gitea.client import Gitea
+
+
+async def authorize_job(
+    *, task: Task, job: Job, repository: Repository, gitea: Gitea
+) -> None:
+    if job.status is not JobStatus.RECEIVED:
+        return
+    permitted = await gitea.has_write_permission(job.repo_owner, job.repo_name, job.requester)
+    event = PermissionGranted(job_id=job.id) if permitted else PermissionDenied(job_id=job.id)
+    outcome = "permission-granted" if permitted else "permission-denied"
+    await repository.apply(f"task:{task.id}:{outcome}", event)

src/agentci/application/worker/comments.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from agentci.engine.events import CommentLinked
+from agentci.engine.model import Job, Task
+from agentci.engine.reducer import render_job_comment
+from agentci.engine.repository import Repository
+from agentci.integrations.gitea.client import Gitea
+
+
+async def reconcile_comment(
+    *,
+    task: Task,
+    job: Job,
+    repository: Repository,
+    gitea: Gitea,
+    bot_username: str,
+) -> None:
+    latest = await repository.get_job(job.id)
+    if latest is None:
+        return
+    body = render_job_comment(latest)
+    comment_id = latest.accepted_comment_id
+    if comment_id is not None and await gitea.update_comment(
+        latest.repo_owner, latest.repo_name, comment_id, body
+    ):
+        return
+    marker = f"<!-- agentci:job id={latest.id} -->"
+    matches = sorted(
+        comment.id
+        for comment in await gitea.issue_comments(
+            latest.repo_owner, latest.repo_name, latest.issue_number
+        )
+        if comment.body.startswith(marker)
+        and comment.author.casefold() == bot_username.casefold()
+    )
+    if matches:
+        comment_id = matches[0]
+    else:
+        comment_id = await gitea.create_comment(
+            latest.repo_owner, latest.repo_name, latest.issue_number, body
+        )
+    await repository.apply(
+        f"task:{task.id}:comment:{comment_id}",
+        CommentLinked(job_id=latest.id, comment_id=comment_id),
+    )
+    await gitea.update_comment(
+        latest.repo_owner, latest.repo_name, comment_id, body
+    )

src/agentci/application/worker/errors.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+
+def safe_error(error: Exception) -> str:
+    message = " ".join(str(error).split())
+    return f"{type(error).__name__}: {message}"[:1000]

src/agentci/application/worker/execution.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from agentci.application.worker.errors import safe_error
+from agentci.engine.events import JobCompleted, JobFailed, JobStarted, ServiceRestarted
+from agentci.engine.events import JobRejected as RejectedEvent
+from agentci.engine.model import Job, JobStatus, Task
+from agentci.engine.repository import Repository
+from agentci.engine.run import JobRun
+from agentci.workflows.dispatch import dispatch
+from agentci.workflows.render import JobRejected
+from agentci.workflows.services import WorkflowServices
+
+
+async def execute_job(
+    *, task: Task, job: Job, repository: Repository, services: WorkflowServices
+) -> None:
+    if job.status is JobStatus.RUNNING:
+        await repository.apply(
+            f"task:{task.id}:interrupted", ServiceRestarted(job_id=job.id)
+        )
+        return
+    if job.status is not JobStatus.QUEUED:
+        return
+    result = await repository.apply(f"task:{task.id}:started", JobStarted(job_id=job.id))
+    running = result.job
+    run = JobRun(repository, job.id, task.id)
+    try:
+        body = await dispatch(running, run, services)
+    except JobRejected as exc:
+        await repository.apply(
+            f"task:{task.id}:rejected", RejectedEvent(job_id=job.id, reason=str(exc))
+        )
+    except Exception as exc:
+        latest = await repository.get_job(job.id)
+        stage = latest.stage if latest else running.stage
+        await repository.apply(
+            f"task:{task.id}:failed",
+            JobFailed(job_id=job.id, error=safe_error(exc), stage=stage),
+        )
+    else:
+        await repository.apply(
+            f"task:{task.id}:completed",
+            JobCompleted(
+                job_id=job.id,
+                comment_body=body or "Agent job completed.",
+            ),
+        )

src/agentci/application/worker/recovery.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from agentci.engine.events import ServiceRestarted
+from agentci.engine.repository import Repository
+
+
+async def recover_jobs(repository: Repository) -> None:
+    await repository.recover_tasks()
+    for job in await repository.running_jobs():
+        await repository.apply(
+            f"recovery:{job.id}:service-restarted",
+            ServiceRestarted(job_id=job.id),
+        )

src/agentci/application/worker/runner.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import suppress
+from pathlib import Path
+
+from agentci.application.worker.authorization import authorize_job
+from agentci.application.worker.comments import reconcile_comment
+from agentci.application.worker.errors import safe_error
+from agentci.application.worker.execution import execute_job
+from agentci.application.worker.recovery import recover_jobs
+from agentci.application.worker.sessions import abort_job_sessions
+from agentci.engine.model import Job, QueueName, Task, TaskKind
+from agentci.engine.repository import Repository
+from agentci.integrations.gitea.client import Gitea
+from agentci.integrations.opencode.client import OpenCode
+from agentci.workflows.services import WorkflowServices
+
+log = logging.getLogger(__name__)
+
+
+class Worker:
+    def __init__(
+        self,
+        *,
+        repository: Repository,
+        gitea: Gitea,
+        opencode: OpenCode,
+        services: WorkflowServices,
+        poll_seconds: float,
+        max_concurrent_jobs: int,
+        workspaces_dir: Path,
+        bot_username: str,
+    ) -> None:
+        self.repository = repository
+        self.gitea = gitea
+        self.opencode = opencode
+        self.services = services
+        self.poll_seconds = poll_seconds
+        self.max_concurrent_jobs = max_concurrent_jobs
+        self.workspaces_dir = workspaces_dir
+        self.bot_username = bot_username
+
+    async def run(self, stop: asyncio.Event) -> None:
+        await self._recover()
+        await asyncio.gather(
+            self._loop(QueueName.CONTROL, stop),
+            *(self._loop(QueueName.JOBS, stop) for _ in range(self.max_concurrent_jobs)),
+        )
+
+    async def _loop(self, queue: QueueName, stop: asyncio.Event) -> None:
+        while not stop.is_set():
+            if queue is QueueName.JOBS and not await self.opencode.ready():
+                await self._wait(stop)
+                continue
+            task = await self.repository.claim_task(queue)
+            if task is None:
+                await self._wait(stop)
+                continue
+            try:
+                await self._handle(task)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                log.exception(
+                    "listener failed",
+                    extra={
+                        "task_id": task.id,
+                        "listener": task.kind.value,
+                        "queue": queue.value,
+                    },
+                )
+                await self.repository.retry_task(task.id, task.attempts, safe_error(exc))
+            else:
+                await self.repository.complete_task(task.id)
+
+    async def _handle(self, task: Task) -> None:
+        job = await self.repository.get_job(task.job_id)
+        if job is None:
+            return
+        match task.kind:
+            case TaskKind.AUTHORIZE:
+                await self._authorize(task, job)
+            case TaskKind.EXECUTE:
+                await self._execute(task, job)
+            case TaskKind.RECONCILE_COMMENT:
+                await self._reconcile(task, job)
+            case TaskKind.FAIL_WORKFLOW:
+                await self.repository.fail_job_workflow(job.id)
+            case TaskKind.ABORT_SESSIONS:
+                await self._abort_job_sessions(job)
+            case _:
+                raise RuntimeError(f"Unknown task kind {task.kind}")
+
+    async def _authorize(self, task: Task, job: Job) -> None:
+        await authorize_job(
+            task=task,
+            job=job,
+            repository=self.repository,
+            gitea=self.gitea,
+        )
+
+    async def _execute(self, task: Task, job: Job) -> None:
+        await execute_job(
+            task=task,
+            job=job,
+            repository=self.repository,
+            services=self.services,
+        )
+
+    async def _reconcile(self, task: Task, job: Job) -> None:
+        await reconcile_comment(
+            task=task,
+            job=job,
+            repository=self.repository,
+            gitea=self.gitea,
+            bot_username=self.bot_username,
+        )
+
+    async def _recover(self) -> None:
+        await recover_jobs(self.repository)
+
+    async def _abort_job_sessions(self, job: Job) -> None:
+        await abort_job_sessions(
+            job=job,
+            repository=self.repository,
+            opencode=self.opencode,
+            workspaces_dir=self.workspaces_dir,
+        )
+
+    async def _wait(self, stop: asyncio.Event) -> None:
+        with suppress(TimeoutError):
+            await asyncio.wait_for(stop.wait(), timeout=self.poll_seconds)

src/agentci/application/worker/sessions.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentci.engine.model import Job
+from agentci.engine.repository import Repository
+from agentci.integrations.opencode.client import OpenCode
+
+
+async def abort_job_sessions(
+    *,
+    job: Job,
+    repository: Repository,
+    opencode: OpenCode,
+    workspaces_dir: Path,
+) -> None:
+    sessions: set[tuple[str, Path]] = set()
+    workflow = await repository.get_workflow(job.workflow_id) if job.workflow_id else None
+    if workflow:
+        sessions.update(
+            (session, workflow.workspace_path)
+            for session in (workflow.primary_session_id, workflow.reviewer_session_id)
+            if session
+        )
+    elif job.runtime_session_id:
+        sessions.add(
+            (job.runtime_session_id, workspaces_dir / f"fix-{job.id}" / "repo")
+        )
+    for session, workspace in sessions:
+        await opencode.abort(session, workspace)

src/agentci/config/__init__.py

@@ -0,0 +1 @@
+"""Service configuration."""

src/agentci/config/settings.py

@@ -45,6 +45,7 @@ class Settings(BaseSettings):
     turn_timeout_seconds: int = Field(default=3600, ge=60)
     install_script_timeout_seconds: int = Field(default=900, ge=1)
     worker_poll_seconds: float = Field(default=1.0, ge=0.1)
+    max_concurrent_jobs: int = Field(default=2, ge=1, le=32)
     install_scripts: Annotated[list[str], NoDecode] = Field(default_factory=list)
     install_scripts_dir: Path = Path("/etc/agentci/install-scripts")
     python_version: str = "3.13"

src/agentci/domain/__init__.py

@@ -1,2 +0,0 @@
-"""Domain types and policies."""
-

src/agentci/engine/__init__.py

@@ -0,0 +1 @@
+"""Durable job and workflow engine."""

src/agentci/engine/_sqlite.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from agentci.engine.events import JobEvent
+from agentci.engine.model import (
+    Job,
+    JobKind,
+    JobStatus,
+    QueueName,
+    Task,
+    TaskKind,
+    Workflow,
+    WorkflowKind,
+    WorkflowStatus,
+)
+from agentci.engine.reducer import Transition
+
+
+def now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def connect(path: Path) -> sqlite3.Connection:
+    connection = sqlite3.connect(path, timeout=30)
+    try:
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA foreign_keys=ON")
+    except Exception:
+        connection.close()
+        raise
+    return connection
+
+
+def initialize(connection: sqlite3.Connection, migrations_dir: Path) -> None:
+    connection.execute(
+        "CREATE TABLE IF NOT EXISTS schema_migrations "
+        "(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)"
+    )
+    applied = {row[0] for row in connection.execute("SELECT version FROM schema_migrations")}
+    for path in sorted(migrations_dir.glob("*.sql")):
+        version = int(path.name.split("_", 1)[0])
+        if version in applied:
+            continue
+        connection.executescript(path.read_text())
+        connection.execute(
+            "INSERT OR IGNORE INTO schema_migrations VALUES (?, ?)",
+            (version, now()),
+        )
+
+
+def insert_event(
+    connection: sqlite3.Connection,
+    event_id: str,
+    event: JobEvent,
+    timestamp: str,
+) -> None:
+    connection.execute(
+        "INSERT INTO job_events VALUES (?, ?, ?, ?, ?)",
+        (event_id, event.job_id, event.type, event.model_dump_json(), timestamp),
+    )
+
+
+def insert_tasks(
+    connection: sqlite3.Connection,
+    event_id: str,
+    transition: Transition,
+    timestamp: str,
+) -> None:
+    for ordinal, task in enumerate(transition.tasks):
+        connection.execute(
+            "INSERT INTO listener_tasks(job_id, source_event_id, ordinal, listener, queue, "
+            "available_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                transition.job.id,
+                event_id,
+                ordinal,
+                task.kind.value,
+                task.queue.value,
+                timestamp,
+                timestamp,
+            ),
+        )
+
+
+def insert_job(connection: sqlite3.Connection, job: Job, timestamp: str) -> None:
+    connection.execute(
+        """INSERT INTO jobs(id, kind, target_key, repo_owner, repo_name, issue_number,
+        pr_number, requester, message, comment_id, delivery_id, receive_sequence, command_body,
+        workflow_id, status, stage, error, runtime_session_id, accepted_comment_id,
+        comment_body, created_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+        (*_job_values(job), timestamp),
+    )
+
+
+def replace_job(
+    connection: sqlite3.Connection,
+    job: Job,
+    previous: Job,
+    timestamp: str,
+) -> None:
+    started = (
+        timestamp
+        if previous.status is JobStatus.QUEUED and job.status is JobStatus.RUNNING
+        else None
+    )
+    terminal = {JobStatus.SUCCEEDED, JobStatus.REJECTED, JobStatus.FAILED}
+    finished = timestamp if previous.status not in terminal and job.status in terminal else None
+    connection.execute(
+        """UPDATE jobs SET kind=?, target_key=?, repo_owner=?, repo_name=?, issue_number=?,
+        pr_number=?, requester=?, message=?, comment_id=?, delivery_id=?, receive_sequence=?,
+        command_body=?, workflow_id=?, status=?, stage=?, error=?, runtime_session_id=?,
+        accepted_comment_id=?, comment_body=?, started_at=COALESCE(started_at, ?),
+        finished_at=COALESCE(finished_at, ?) WHERE id=?""",
+        (*_job_values(job)[1:], started, finished, job.id),
+    )
+
+
+def optional_job(connection: sqlite3.Connection, job_id: str) -> Job | None:
+    row = connection.execute("SELECT * FROM jobs WHERE id=?", (job_id,)).fetchone()
+    return job_from_row(row) if row else None
+
+
+def required_job(connection: sqlite3.Connection, job_id: str) -> Job:
+    job = optional_job(connection, job_id)
+    if job is None:
+        raise KeyError(f"Unknown job {job_id}")
+    return job
+
+
+def job_from_row(row: sqlite3.Row) -> Job:
+    return Job(
+        id=row["id"],
+        kind=JobKind(row["kind"]) if row["kind"] else None,
+        target_key=row["target_key"],
+        repo_owner=row["repo_owner"],
+        repo_name=row["repo_name"],
+        issue_number=row["issue_number"],
+        pr_number=row["pr_number"],
+        requester=row["requester"],
+        message=row["message"],
+        comment_id=row["comment_id"],
+        delivery_id=row["delivery_id"],
+        receive_sequence=row["receive_sequence"],
+        command_body=row["command_body"],
+        workflow_id=row["workflow_id"],
+        status=JobStatus(row["status"]),
+        stage=row["stage"],
+        error=row["error"],
+        runtime_session_id=row["runtime_session_id"],
+        accepted_comment_id=row["accepted_comment_id"],
+        comment_body=row["comment_body"],
+    )
+
+
+def insert_workflow(
+    connection: sqlite3.Connection,
+    workflow: Workflow,
+    timestamp: str,
+) -> None:
+    connection.execute(
+        """INSERT INTO workflows(id, kind, repo_owner, repo_name, issue_number, pr_number,
+        base_sha, branch, workspace_path, primary_session_id, reviewer_session_id, artifact,
+        review_json, status, runtime, created_at, updated_at)
+        VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+        (
+            workflow.id,
+            workflow.kind.value,
+            workflow.repo_owner,
+            workflow.repo_name,
+            workflow.issue_number,
+            workflow.pr_number,
+            workflow.base_sha,
+            workflow.branch,
+            str(workflow.workspace_path),
+            workflow.primary_session_id,
+            workflow.reviewer_session_id,
+            workflow.artifact,
+            workflow.review_json,
+            workflow.status.value,
+            workflow.runtime,
+            timestamp,
+            timestamp,
+        ),
+    )
+
+
+def workflow_from_row(row: sqlite3.Row | None) -> Workflow | None:
+    if row is None:
+        return None
+    return Workflow(
+        id=row["id"],
+        kind=WorkflowKind(row["kind"]),
+        repo_owner=row["repo_owner"],
+        repo_name=row["repo_name"],
+        issue_number=row["issue_number"],
+        pr_number=row["pr_number"],
+        base_sha=row["base_sha"],
+        runtime=row["runtime"],
+        branch=row["branch"],
+        workspace_path=Path(row["workspace_path"]),
+        primary_session_id=row["primary_session_id"],
+        reviewer_session_id=row["reviewer_session_id"],
+        artifact=row["artifact"],
+        review_json=row["review_json"],
+        status=WorkflowStatus(row["status"]),
+    )
+
+
+def claim_task(connection: sqlite3.Connection, queue: str) -> Task | None:
+    connection.execute("BEGIN IMMEDIATE")
+    fifo = ""
+    if queue == QueueName.JOBS.value:
+        fifo = """AND NOT EXISTS (
+            SELECT 1 FROM jobs earlier WHERE earlier.receive_sequence < j.receive_sequence
+            AND earlier.target_key = j.target_key
+            AND earlier.status IN ('received', 'queued', 'running'))"""
+    row = connection.execute(
+        f"""SELECT t.* FROM listener_tasks t JOIN jobs j ON j.id=t.job_id
+        WHERE t.queue=? AND t.status='pending' AND t.available_at<=? {fifo}
+        ORDER BY {"j.receive_sequence" if queue == QueueName.JOBS.value else "t.id"} LIMIT 1""",
+        (queue, now()),
+    ).fetchone()
+    if row is None:
+        connection.commit()
+        return None
+    changed = connection.execute(
+        "UPDATE listener_tasks SET status='running', started_at=?, attempts=attempts+1 "
+        "WHERE id=? AND status='pending'",
+        (now(), row["id"]),
+    )
+    if changed.rowcount != 1:
+        connection.rollback()
+        return None
+    connection.commit()
+    return Task(
+        id=row["id"],
+        job_id=row["job_id"],
+        source_event_id=row["source_event_id"],
+        kind=TaskKind(row["listener"]),
+        queue=QueueName(row["queue"]),
+        attempts=row["attempts"] + 1,
+    )
+
+
+def _job_values(job: Job) -> tuple[object, ...]:
+    return (
+        job.id,
+        job.kind.value if job.kind else None,
+        job.target_key,
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+        job.pr_number,
+        job.requester,
+        job.message,
+        job.comment_id,
+        job.delivery_id,
+        job.receive_sequence,
+        job.command_body,
+        job.workflow_id,
+        job.status.value,
+        job.stage,
+        job.error,
+        job.runtime_session_id,
+        job.accepted_comment_id,
+        job.comment_body,
+    )

src/agentci/engine/commands.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import re
 
-from agentci.domain.models import CommandName, JobKind, ParsedCommand
+from agentci.engine.model import CommandName, JobKind, ParsedCommand
 
 COMMAND_RE = re.compile(r"^/agent[ \t]+([a-z]+)(?:[ \t\r\n]+([\s\S]*))?$")
 

src/agentci/engine/events.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentci.engine.model import Workflow
+
+
+class Event(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    job_id: str
+
+
+class CommandReceived(Event):
+    type: Literal["command_received"] = "command_received"
+    delivery_id: str
+    receive_sequence: int
+    command_body: str
+    target_key: str
+    repo_owner: str
+    repo_name: str
+    issue_number: int
+    pr_number: int | None
+    requester: str
+    comment_id: int
+
+
+class PermissionGranted(Event):
+    type: Literal["permission_granted"] = "permission_granted"
+
+
+class PermissionDenied(Event):
+    type: Literal["permission_denied"] = "permission_denied"
+
+
+class JobStarted(Event):
+    type: Literal["job_started"] = "job_started"
+
+
+class JobProgress(Event):
+    type: Literal["job_progress"] = "job_progress"
+    stage: str
+
+
+class WorkflowCreated(Event):
+    type: Literal["workflow_created"] = "workflow_created"
+    workflow: Workflow
+    stage: str
+
+
+class WorkflowLinked(Event):
+    type: Literal["workflow_linked"] = "workflow_linked"
+    workflow_id: str
+    stage: str
+
+
+class RuntimeSessionLinked(Event):
+    type: Literal["runtime_session_linked"] = "runtime_session_linked"
+    session_id: str
+
+
+class JobCompleted(Event):
+    type: Literal["job_completed"] = "job_completed"
+    comment_body: str
+
+
+class JobRejected(Event):
+    type: Literal["job_rejected"] = "job_rejected"
+    reason: str
+
+
+class JobFailed(Event):
+    type: Literal["job_failed"] = "job_failed"
+    error: str
+    stage: str
+
+
+class ServiceRestarted(Event):
+    type: Literal["service_restarted"] = "service_restarted"
+
+
+class CommentLinked(Event):
+    type: Literal["comment_linked"] = "comment_linked"
+    comment_id: int
+
+
+JobEvent = Annotated[
+    CommandReceived
+    | PermissionGranted
+    | PermissionDenied
+    | JobStarted
+    | JobProgress
+    | WorkflowCreated
+    | WorkflowLinked
+    | RuntimeSessionLinked
+    | JobCompleted
+    | JobRejected
+    | JobFailed
+    | ServiceRestarted
+    | CommentLinked,
+    Field(discriminator="type"),
+]

src/agentci/engine/model.py

@@ -4,8 +4,6 @@ from dataclasses import dataclass
 from enum import StrEnum
 from pathlib import Path
 
-from pydantic import BaseModel, Field
-
 
 class CommandName(StrEnum):
     PLAN = "plan"
@@ -25,6 +23,7 @@ class JobKind(StrEnum):
 
 
 class JobStatus(StrEnum):
+    RECEIVED = "received"
     QUEUED = "queued"
     RUNNING = "running"
     SUCCEEDED = "succeeded"
@@ -43,43 +42,17 @@ class WorkflowStatus(StrEnum):
     FAILED = "failed"
 
 
-class ReviewSeverity(StrEnum):
-    BLOCKING = "blocking"
-    MAJOR = "major"
-    MINOR = "minor"
+class TaskKind(StrEnum):
+    AUTHORIZE = "authorize"
+    EXECUTE = "execute"
+    RECONCILE_COMMENT = "reconcile_comment"
+    FAIL_WORKFLOW = "fail_workflow"
+    ABORT_SESSIONS = "abort_sessions"
 
 
-class PlanArtifact(BaseModel):
-    plan_markdown: str = Field(min_length=1)
-
-
-class DiscussionReply(BaseModel):
-    markdown: str = Field(min_length=1)
-
-
-class AgentResult(BaseModel):
-    summary_markdown: str = Field(min_length=1)
-    tests: list[str] = Field(default_factory=list)
-
-
-class ReviewFinding(BaseModel):
-    severity: ReviewSeverity
-    title: str
-    detail: str
-    location: str | None = None
-    recommendation: str
-
-
-class ReviewReport(BaseModel):
-    summary: str
-    findings: list[ReviewFinding] = Field(default_factory=list)
-
-    @property
-    def has_serious_findings(self) -> bool:
-        return any(
-            finding.severity in {ReviewSeverity.BLOCKING, ReviewSeverity.MAJOR}
-            for finding in self.findings
-        )
+class QueueName(StrEnum):
+    CONTROL = "control"
+    JOBS = "jobs"
 
 
 @dataclass(frozen=True)
@@ -89,7 +62,7 @@ class ParsedCommand:
 
 
 @dataclass(frozen=True)
-class CommandEvent:
+class IncomingCommand:
     delivery_id: str
     comment_id: int
     repo_owner: str
@@ -109,26 +82,35 @@ class CommandEvent:
         return f"{self.repo_owner}/{self.repo_name}:{target}"
 
 
-@dataclass
+@dataclass(frozen=True)
 class Job:
     id: str
-    kind: JobKind
     target_key: str
     repo_owner: str
     repo_name: str
     issue_number: int
     pr_number: int | None
     requester: str
-    message: str
     comment_id: int
+    delivery_id: str
+    receive_sequence: int
+    command_body: str
+    kind: JobKind | None = None
+    message: str | None = None
+    status: JobStatus = JobStatus.RECEIVED
+    stage: str = "received"
+    error: str | None = None
     workflow_id: str | None = None
-    status: JobStatus = JobStatus.QUEUED
-    stage: str = "queued"
-    accepted_comment_id: int | None = None
     runtime_session_id: str | None = None
+    accepted_comment_id: int | None = None
+    comment_body: str | None = None
+
+    @property
+    def is_pull_request(self) -> bool:
+        return self.pr_number is not None
 
 
-@dataclass
+@dataclass(frozen=True)
 class Workflow:
     id: str
     kind: WorkflowKind
@@ -145,3 +127,19 @@ class Workflow:
     artifact: str | None = None
     review_json: str | None = None
     status: WorkflowStatus = WorkflowStatus.ACTIVE
+
+
+@dataclass(frozen=True)
+class TaskRequest:
+    kind: TaskKind
+    queue: QueueName
+
+
+@dataclass(frozen=True)
+class Task:
+    id: int
+    job_id: str
+    source_event_id: str
+    kind: TaskKind
+    queue: QueueName
+    attempts: int

src/agentci/engine/reducer.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from agentci.engine.commands import CommandError, parse_command, resolve_job_kind
+from agentci.engine.events import (
+    CommandReceived,
+    CommentLinked,
+    JobCompleted,
+    JobEvent,
+    JobFailed,
+    JobProgress,
+    JobRejected,
+    JobStarted,
+    PermissionDenied,
+    PermissionGranted,
+    RuntimeSessionLinked,
+    ServiceRestarted,
+    WorkflowCreated,
+    WorkflowLinked,
+)
+from agentci.engine.model import Job, JobStatus, QueueName, TaskKind, TaskRequest
+
+
+class InvalidTransition(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Transition:
+    job: Job
+    tasks: tuple[TaskRequest, ...] = ()
+
+
+RECONCILE = TaskRequest(TaskKind.RECONCILE_COMMENT, QueueName.CONTROL)
+
+
+def reduce_job(current: Job | None, event: JobEvent) -> Transition:
+    if current is None:
+        if not isinstance(event, CommandReceived):
+            raise InvalidTransition("Only CommandReceived can create a job")
+        job = Job(
+            id=event.job_id,
+            target_key=event.target_key,
+            repo_owner=event.repo_owner,
+            repo_name=event.repo_name,
+            issue_number=event.issue_number,
+            pr_number=event.pr_number,
+            requester=event.requester,
+            comment_id=event.comment_id,
+            delivery_id=event.delivery_id,
+            receive_sequence=event.receive_sequence,
+            command_body=event.command_body,
+        )
+        task = TaskRequest(TaskKind.AUTHORIZE, QueueName.CONTROL)
+        return Transition(job, (task,))
+    if event.job_id != current.id:
+        raise InvalidTransition("Event job ID does not match state")
+    if isinstance(event, CommentLinked):
+        return Transition(replace(current, accepted_comment_id=event.comment_id))
+    if isinstance(event, ServiceRestarted):
+        if current.status is not JobStatus.RUNNING:
+            return Transition(current)
+        failed = replace(
+            current,
+            status=JobStatus.FAILED,
+            stage="interrupted",
+            error="Service restarted during an active OpenCode turn",
+        )
+        tasks = [TaskRequest(TaskKind.ABORT_SESSIONS, QueueName.CONTROL), RECONCILE]
+        if current.workflow_id:
+            tasks.insert(1, TaskRequest(TaskKind.FAIL_WORKFLOW, QueueName.CONTROL))
+        return Transition(failed, tuple(tasks))
+    if current.status is JobStatus.RECEIVED:
+        return _received(current, event)
+    if current.status is JobStatus.QUEUED and isinstance(event, JobStarted):
+        return Transition(
+            replace(current, status=JobStatus.RUNNING, stage="starting"),
+            (RECONCILE,),
+        )
+    if current.status is JobStatus.RUNNING:
+        return _running(current, event)
+    raise InvalidTransition(f"{event.type} is invalid while job is {current.status}")
+
+
+def _received(current: Job, event: JobEvent) -> Transition:
+    if isinstance(event, PermissionDenied):
+        reason = "Agent command rejected: repository write permission is required."
+        return Transition(
+            replace(current, status=JobStatus.REJECTED, stage="rejected", error=reason),
+            (RECONCILE,),
+        )
+    if not isinstance(event, PermissionGranted):
+        raise InvalidTransition(f"{event.type} is invalid while job is received")
+    try:
+        command = parse_command(current.command_body)
+        if command is None:
+            raise CommandError("Invalid agent command.")
+        kind = resolve_job_kind(command, is_pull_request=current.is_pull_request)
+    except CommandError as exc:
+        return Transition(
+            replace(current, status=JobStatus.REJECTED, stage="rejected", error=str(exc)),
+            (RECONCILE,),
+        )
+    queued = replace(
+        current,
+        kind=kind,
+        message=command.message,
+        status=JobStatus.QUEUED,
+        stage="queued",
+    )
+    tasks = (
+        TaskRequest(TaskKind.EXECUTE, QueueName.JOBS),
+        RECONCILE,
+    )
+    return Transition(queued, tasks)
+
+
+def _running(current: Job, event: JobEvent) -> Transition:
+    if isinstance(event, JobProgress):
+        return Transition(replace(current, stage=event.stage))
+    if isinstance(event, WorkflowCreated):
+        return Transition(replace(current, workflow_id=event.workflow.id, stage=event.stage))
+    if isinstance(event, WorkflowLinked):
+        return Transition(replace(current, workflow_id=event.workflow_id, stage=event.stage))
+    if isinstance(event, RuntimeSessionLinked):
+        return Transition(replace(current, runtime_session_id=event.session_id))
+    if isinstance(event, JobCompleted):
+        return Transition(
+            replace(
+                current,
+                status=JobStatus.SUCCEEDED,
+                stage="completed",
+                comment_body=event.comment_body,
+            ),
+            (RECONCILE,),
+        )
+    if isinstance(event, (JobRejected, JobFailed)):
+        rejected = isinstance(event, JobRejected)
+        error = event.reason if rejected else event.error
+        stage = "rejected" if rejected else event.stage
+        status = JobStatus.REJECTED if rejected else JobStatus.FAILED
+        tasks = [RECONCILE]
+        if current.workflow_id:
+            tasks.append(TaskRequest(TaskKind.FAIL_WORKFLOW, QueueName.CONTROL))
+        return Transition(
+            replace(current, status=status, stage=stage, error=error),
+            tuple(tasks),
+        )
+    raise InvalidTransition(f"{event.type} is invalid while job is running")
+
+
+def render_job_comment(job: Job) -> str:
+    marker = f"<!-- agentci:job id={job.id} -->"
+    if job.status is JobStatus.SUCCEEDED and job.comment_body:
+        body = job.comment_body
+    elif job.status is JobStatus.REJECTED:
+        body = f"Agent job `{job.id}` was rejected: {job.error}"
+    elif job.status is JobStatus.FAILED:
+        body = f"Agent job `{job.id}` failed during `{job.stage}`: {job.error}"
+    else:
+        kind = job.kind.value if job.kind else "command"
+        body = f"Agent job `{job.id}` {job.status.value} (`{kind}`; stage: `{job.stage}`)."
+    return f"{marker}\n{body}"

src/agentci/engine/repository.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import logging
+import sqlite3
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TypeVar
+from uuid import UUID, uuid5
+
+from agentci.engine import _sqlite
+from agentci.engine.events import CommandReceived, JobEvent, WorkflowCreated
+from agentci.engine.model import (
+    IncomingCommand,
+    Job,
+    QueueName,
+    Task,
+    Workflow,
+    WorkflowKind,
+    WorkflowStatus,
+)
+from agentci.engine.reducer import reduce_job
+
+T = TypeVar("T")
+log = logging.getLogger(__name__)
+JOB_NAMESPACE = UUID("59565f0f-f17d-4b80-bfba-7ef1fbfd38eb")
+
+
+@dataclass(frozen=True)
+class ApplyResult:
+    job: Job
+    duplicate: bool
+
+
+class Repository:
+    def __init__(self, database_path: Path, migrations_dir: Path | None = None) -> None:
+        self.database_path = database_path
+        self.migrations_dir = migrations_dir or Path(__file__).parent.parent / "migrations"
+
+    async def initialize(self) -> None:
+        log.info("database initialization started", extra={"operation": "database.initialize"})
+        self.database_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            await self._run(lambda connection: _sqlite.initialize(connection, self.migrations_dir))
+        except Exception:
+            log.exception(
+                "database initialization failed",
+                extra={"operation": "database.initialize"},
+            )
+            raise
+        log.info("database initialization completed", extra={"operation": "database.initialize"})
+
+    async def accept(self, command: IncomingCommand) -> ApplyResult:
+        job_id = str(uuid5(JOB_NAMESPACE, command.delivery_id))
+        event_id = f"delivery:{command.delivery_id}"
+
+        def operation(connection: sqlite3.Connection) -> ApplyResult:
+            connection.execute("BEGIN IMMEDIATE")
+            duplicate = connection.execute(
+                "SELECT job_id FROM job_events WHERE event_id=?", (event_id,)
+            ).fetchone()
+            if duplicate:
+                job = _sqlite.required_job(connection, duplicate["job_id"])
+                connection.commit()
+                return ApplyResult(job, True)
+            sequence = connection.execute(
+                "SELECT COALESCE(MAX(receive_sequence), 0) + 1 FROM jobs"
+            ).fetchone()[0]
+            event = CommandReceived(
+                job_id=job_id,
+                delivery_id=command.delivery_id,
+                receive_sequence=sequence,
+                command_body=command.body,
+                target_key=command.target_key,
+                repo_owner=command.repo_owner,
+                repo_name=command.repo_name,
+                issue_number=command.issue_number,
+                pr_number=command.pr_number,
+                requester=command.requester,
+                comment_id=command.comment_id,
+            )
+            transition = reduce_job(None, event)
+            timestamp = _sqlite.now()
+            _sqlite.insert_event(connection, event_id, event, timestamp)
+            _sqlite.insert_job(connection, transition.job, timestamp)
+            _sqlite.insert_tasks(connection, event_id, transition, timestamp)
+            connection.commit()
+            return ApplyResult(transition.job, False)
+
+        return await self._run(operation)
+
+    async def apply(self, event_id: str, event: JobEvent) -> ApplyResult:
+        def operation(connection: sqlite3.Connection) -> ApplyResult:
+            connection.execute("BEGIN IMMEDIATE")
+            duplicate = connection.execute(
+                "SELECT job_id FROM job_events WHERE event_id=?", (event_id,)
+            ).fetchone()
+            if duplicate:
+                existing_job_id = duplicate["job_id"]
+                if existing_job_id != event.job_id:
+                    raise RuntimeError(
+                        f"Event ID {event_id!r} belongs to job {existing_job_id!r}, "
+                        f"not {event.job_id!r}"
+                    )
+                job = _sqlite.required_job(connection, existing_job_id)
+                connection.commit()
+                return ApplyResult(job, True)
+            current = _sqlite.required_job(connection, event.job_id)
+            transition = reduce_job(current, event)
+            timestamp = _sqlite.now()
+            _sqlite.insert_event(connection, event_id, event, timestamp)
+            if isinstance(event, WorkflowCreated):
+                _sqlite.insert_workflow(connection, event.workflow, timestamp)
+            _sqlite.replace_job(connection, transition.job, current, timestamp)
+            _sqlite.insert_tasks(connection, event_id, transition, timestamp)
+            connection.commit()
+            return ApplyResult(transition.job, False)
+
+        return await self._run(operation)
+
+    async def get_job(self, job_id: str) -> Job | None:
+        return await self._run(lambda connection: _sqlite.optional_job(connection, job_id))
+
+    async def claim_task(self, queue: QueueName | str) -> Task | None:
+        queue_name = queue.value if isinstance(queue, QueueName) else queue
+        return await self._run(lambda connection: _sqlite.claim_task(connection, queue_name))
+
+    async def complete_task(self, task_id: int) -> None:
+        await self._run(
+            lambda connection: connection.execute(
+                "UPDATE listener_tasks SET status='completed', finished_at=? WHERE id=?",
+                (_sqlite.now(), task_id),
+            )
+        )
+
+    async def retry_task(self, task_id: int, attempts: int, error: str) -> None:
+        delay = min(2 ** min(attempts, 8), 300)
+        available = (datetime.now(UTC) + timedelta(seconds=delay)).isoformat()
+        await self._run(
+            lambda connection: connection.execute(
+                "UPDATE listener_tasks SET status='pending', available_at=?, error=? WHERE id=?",
+                (available, error[:1000], task_id),
+            )
+        )
+
+    async def recover_tasks(self) -> None:
+        def operation(connection: sqlite3.Connection) -> None:
+            with connection:
+                connection.execute(
+                    """UPDATE listener_tasks SET status='pending', started_at=NULL
+                    WHERE status='running' AND queue='control'"""
+                )
+                connection.execute(
+                    """UPDATE listener_tasks SET status='pending', started_at=NULL
+                    WHERE status='running' AND listener='execute' AND job_id IN
+                    (SELECT id FROM jobs WHERE status='queued')"""
+                )
+                connection.execute(
+                    """UPDATE listener_tasks SET status='failed', finished_at=?,
+                    error='Service restarted after execution began'
+                    WHERE status='running' AND listener='execute' AND job_id IN
+                    (SELECT id FROM jobs WHERE status<>'queued')""",
+                    (_sqlite.now(),),
+                )
+
+        await self._run(operation)
+
+    async def running_jobs(self) -> list[Job]:
+        return await self._run(
+            lambda connection: [
+                _sqlite.job_from_row(row)
+                for row in connection.execute("SELECT * FROM jobs WHERE status='running'")
+            ]
+        )
+
+    async def operational_comment_ids(self, owner: str, repo: str, issue: int) -> set[int]:
+        return await self._run(
+            lambda connection: {
+                value
+                for row in connection.execute(
+                    "SELECT accepted_comment_id, started_comment_id FROM jobs "
+                    "WHERE repo_owner=? AND repo_name=? AND issue_number=?",
+                    (owner, repo, issue),
+                )
+                for value in row
+                if value is not None
+            }
+        )
+
+    async def get_workflow(self, workflow_id: str) -> Workflow | None:
+        return await self._run(
+            lambda connection: _sqlite.workflow_from_row(
+                connection.execute("SELECT * FROM workflows WHERE id=?", (workflow_id,)).fetchone()
+            )
+        )
+
+    async def save_workflow(self, workflow: Workflow) -> None:
+        def operation(connection: sqlite3.Connection) -> None:
+            updated = connection.execute(
+                """UPDATE workflows SET pr_number=?, branch=?, primary_session_id=?,
+                reviewer_session_id=?, artifact=?, review_json=?, status=?, updated_at=?
+                WHERE id=?""",
+                (
+                    workflow.pr_number,
+                    workflow.branch,
+                    workflow.primary_session_id,
+                    workflow.reviewer_session_id,
+                    workflow.artifact,
+                    workflow.review_json,
+                    workflow.status.value,
+                    _sqlite.now(),
+                    workflow.id,
+                ),
+            )
+            if updated.rowcount != 1:
+                raise KeyError(f"Unknown workflow {workflow.id}")
+
+        await self._run(operation)
+
+    async def latest_workflow(
+        self,
+        owner: str,
+        repo: str,
+        issue: int,
+        kind: WorkflowKind,
+    ) -> Workflow | None:
+        return await self._run(
+            lambda connection: _sqlite.workflow_from_row(
+                connection.execute(
+                    """SELECT * FROM workflows
+                    WHERE repo_owner=? AND repo_name=? AND issue_number=?
+                      AND kind=? AND status=?
+                    ORDER BY created_at DESC LIMIT 1""",
+                    (owner, repo, issue, kind.value, WorkflowStatus.COMPLETED.value),
+                ).fetchone()
+            )
+        )
+
+    async def workflow_for_pr(self, owner: str, repo: str, pr: int) -> Workflow | None:
+        return await self._run(
+            lambda connection: _sqlite.workflow_from_row(
+                connection.execute(
+                    """SELECT * FROM workflows
+                    WHERE repo_owner=? AND repo_name=? AND pr_number=? AND kind=?
+                    ORDER BY created_at DESC LIMIT 1""",
+                    (owner, repo, pr, WorkflowKind.IMPLEMENT.value),
+                ).fetchone()
+            )
+        )
+
+    async def implementation_workflows(self, owner: str, repo: str, issue: int) -> list[Workflow]:
+        return await self._run(
+            lambda connection: [
+                workflow
+                for row in connection.execute(
+                    """SELECT * FROM workflows
+                    WHERE repo_owner=? AND repo_name=? AND issue_number=? AND kind=?
+                      AND pr_number IS NOT NULL
+                    ORDER BY created_at DESC""",
+                    (owner, repo, issue, WorkflowKind.IMPLEMENT.value),
+                )
+                if (workflow := _sqlite.workflow_from_row(row)) is not None
+            ]
+        )
+
+    async def fail_job_workflow(self, job_id: str) -> None:
+        await self._run(
+            lambda connection: connection.execute(
+                """UPDATE workflows SET status=?, updated_at=?
+                WHERE id=(SELECT workflow_id FROM jobs WHERE id=?)
+                  AND status=?""",
+                (
+                    WorkflowStatus.FAILED.value,
+                    _sqlite.now(),
+                    job_id,
+                    WorkflowStatus.ACTIVE.value,
+                ),
+            )
+        )
+
+    async def _run(self, operation: Callable[[sqlite3.Connection], T]) -> T:
+        connection = _sqlite.connect(self.database_path)
+        try:
+            with connection:
+                return operation(connection)
+        finally:
+            connection.close()

src/agentci/engine/run.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from agentci.engine.events import (
+    JobProgress,
+    RuntimeSessionLinked,
+    WorkflowCreated,
+    WorkflowLinked,
+)
+from agentci.engine.model import Workflow
+from agentci.engine.repository import Repository
+
+type ReportEvent = JobProgress | RuntimeSessionLinked | WorkflowCreated | WorkflowLinked
+
+
+class JobRun:
+    def __init__(self, repository: Repository, job_id: str, task_id: int) -> None:
+        self.repository = repository
+        self.job_id = job_id
+        self.task_id = task_id
+        self._sequence = 0
+
+    async def stage(self, stage: str) -> None:
+        await self._emit(JobProgress(job_id=self.job_id, stage=stage))
+
+    async def create_workflow(self, workflow: Workflow, stage: str) -> None:
+        await self._emit(WorkflowCreated(job_id=self.job_id, workflow=workflow, stage=stage))
+
+    async def link_workflow(self, workflow_id: str, stage: str) -> None:
+        await self._emit(
+            WorkflowLinked(job_id=self.job_id, workflow_id=workflow_id, stage=stage)
+        )
+
+    async def link_session(self, session_id: str) -> None:
+        await self._emit(RuntimeSessionLinked(job_id=self.job_id, session_id=session_id))
+
+    async def _emit(self, event: ReportEvent) -> None:
+        self._sequence += 1
+        event_id = f"task:{self.task_id}:report:{self._sequence}"
+        await self.repository.apply(event_id, event)

src/agentci/integrations/__init__.py

@@ -0,0 +1 @@
+"""External service and process integrations."""

src/agentci/integrations/codegraph.py

@@ -13,7 +13,7 @@ class CodeGraphError(RuntimeError):
     pass
 
 
-class CodeGraphClient:
+class CodeGraph:
     async def prepare(self, workspace: Path) -> None:
         self._exclude_index(workspace)
         index = workspace / ".codegraph" / "codegraph.db"

src/agentci/integrations/development.py

@@ -32,6 +32,7 @@ class DevelopmentEnvironment:
         self.timeout_seconds = timeout_seconds
         self.python_version = python_version
         self.dotnet_channel = dotnet_channel
+        self._prepare_lock = asyncio.Lock()
 
     @property
     def description(self) -> str:
@@ -40,10 +41,11 @@ class DevelopmentEnvironment:
     async def prepare(self, workspace: Path) -> None:
         if not self.scripts:
             return
-        self.tools_dir.mkdir(parents=True, exist_ok=True)
-        (self.tools_dir / "bin").mkdir(exist_ok=True)
-        for name in self.scripts:
-            await self._run(name, self._resolve(name), workspace)
+        async with self._prepare_lock:
+            self.tools_dir.mkdir(parents=True, exist_ok=True)
+            (self.tools_dir / "bin").mkdir(exist_ok=True)
+            for name in self.scripts:
+                await self._run(name, self._resolve(name), workspace)
 
     def _resolve(self, name: str) -> Path:
         path = self.scripts_dir / name

src/agentci/integrations/git.py

@@ -13,7 +13,7 @@ class GitError(RuntimeError):
     pass
 
 
-class GitClient:
+class Git:
     def __init__(
         self,
         *,
@@ -31,9 +31,6 @@ class GitClient:
         self.commit_name = commit_name
         self.commit_email = commit_email
 
-    def clone_url(self, owner: str, repo: str) -> str:
-        return f"{self.gitea_url}/{owner}/{repo}.git"
-
     async def clone(
         self,
         owner: str,
@@ -47,7 +44,7 @@ class GitClient:
             "--branch",
             branch,
             "--single-branch",
-            self.clone_url(owner, repo),
+            f"{self.gitea_url}/{owner}/{repo}.git",
             str(destination),
             cwd=destination.parent,
             authenticated=True,
@@ -85,6 +82,7 @@ class GitClient:
             "-m",
             message,
             cwd=workspace,
+            command_name="commit",
         )
         return await self.current_sha(workspace)
 
@@ -101,8 +99,10 @@ class GitClient:
         *args: str,
         cwd: Path,
         authenticated: bool = False,
+        command_name: str | None = None,
     ) -> str:
-        operation = f"git.{args[0]}"
+        command_name = command_name or args[0]
+        operation = f"git.{command_name}"
         started = monotonic()
         log.info("git step started", extra={"operation": operation})
         environment = os.environ.copy()
@@ -130,14 +130,14 @@ class GitClient:
                 "git step could not start",
                 extra={"operation": operation, "duration_ms": _elapsed_ms(started)},
             )
-            raise GitError(f"Could not run git {args[0]}: {exc}") from exc
+            raise GitError(f"Could not run git {command_name}: {exc}") from exc
         if process.returncode:
             detail = stderr.decode(errors="replace").strip()
             log.error(
                 "git step failed",
                 extra={"operation": operation, "duration_ms": _elapsed_ms(started)},
             )
-            raise GitError(f"git {args[0]} failed: {detail[-1000:]}")
+            raise GitError(f"git {command_name} failed: {detail[-1000:]}")
         log.info(
             "git step completed",
             extra={"operation": operation, "duration_ms": _elapsed_ms(started)},

src/agentci/integrations/gitea/__init__.py

@@ -0,0 +1 @@
+"""Gitea API and webhook integration."""

src/agentci/integrations/gitea/client.py

@@ -7,12 +7,7 @@ from typing import Any
 
 import httpx
 
-from agentci.adapters.gitea_models import (
-    CommentInfo,
-    IssueInfo,
-    PullRequestInfo,
-    RepositoryInfo,
-)
+from agentci.integrations.gitea.models import CommentInfo, IssueInfo, PullRequestInfo
 
 log = logging.getLogger(__name__)
 
@@ -21,14 +16,22 @@ class GiteaError(RuntimeError):
     pass
 
 
-class GiteaClient:
-    def __init__(self, base_url: str, token: str, *, retries: int = 3) -> None:
+class Gitea:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        retries: int = 3,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
         self.base_url = base_url.rstrip("/")
         self.retries = retries
         self.client = httpx.AsyncClient(
             base_url=f"{self.base_url}/api/v1",
             headers={"Authorization": f"token {token}", "Accept": "application/json"},
             timeout=30,
+            transport=transport,
         )
 
     async def close(self) -> None:
@@ -41,14 +44,9 @@ class GiteaClient:
         permission = str(response.json().get("permission", "")).lower()
         return permission in {"write", "admin", "owner"}
 
-    async def repository(self, owner: str, repo: str) -> RepositoryInfo:
+    async def default_branch(self, owner: str, repo: str) -> str:
         data = (await self._request("GET", f"/repos/{owner}/{repo}")).json()
-        return RepositoryInfo(
-            owner=owner,
-            name=repo,
-            full_name=data.get("full_name", f"{owner}/{repo}"),
-            default_branch=data["default_branch"],
-        )
+        return str(data["default_branch"])
 
     async def issue(self, owner: str, repo: str, number: int) -> IssueInfo:
         data = (await self._request("GET", f"/repos/{owner}/{repo}/issues/{number}")).json()
@@ -105,12 +103,14 @@ class GiteaClient:
         )
         return int(response.json()["id"])
 
-    async def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> None:
-        await self._request(
+    async def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> bool:
+        response = await self._request(
             "PATCH",
             f"/repos/{owner}/{repo}/issues/comments/{comment_id}",
             json={"body": body},
+            allow_not_found=True,
         )
+        return response.status_code != 404
 
     async def create_pull_request(
         self,

src/agentci/integrations/gitea/models.py

@@ -3,14 +3,6 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 
-@dataclass(frozen=True)
-class RepositoryInfo:
-    owner: str
-    name: str
-    full_name: str
-    default_branch: str
-
-
 @dataclass(frozen=True)
 class IssueInfo:
     number: int
@@ -43,4 +35,3 @@ class PullRequestInfo:
     @property
     def is_open(self) -> bool:
         return self.state == "open" and not self.merged
-

src/agentci/integrations/gitea/webhooks.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Any
+
+from agentci.engine.model import IncomingCommand
+
+SUPPORTED_EVENTS = {
+    "issue_comment",
+    "pull_request_comment",
+    "pull_request_review_comment",
+}
+
+
+def valid_signature(secret: bytes, body: bytes, signature: str) -> bool:
+    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
+    return bool(signature) and hmac.compare_digest(expected, signature)
+
+
+def incoming_command_from_payload(
+    delivery_id: str, payload: dict[str, Any]
+) -> IncomingCommand | None:
+    if payload.get("action") != "created":
+        return None
+    comment = payload["comment"]
+    repository = payload["repository"]
+    owner = repository["owner"]
+    owner_name = owner.get("login") or owner.get("username") or owner["name"]
+    pull = payload.get("pull_request")
+    is_pull = bool(payload.get("is_pull") or pull)
+    issue = payload.get("issue")
+    target = pull or issue
+    if target is None:
+        raise ValueError("Comment payload has no issue or pull request")
+    number = int(target["number"])
+    return IncomingCommand(
+        delivery_id=delivery_id,
+        comment_id=int(comment["id"]),
+        repo_owner=owner_name,
+        repo_name=repository["name"],
+        issue_number=number,
+        pr_number=number if is_pull else None,
+        requester=comment["user"]["login"],
+        body=comment.get("body") or "",
+    )

src/agentci/integrations/opencode/__init__.py

@@ -0,0 +1 @@
+"""OpenCode API integration."""

src/agentci/integrations/opencode/client.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from contextlib import suppress
 from pathlib import Path
 from time import monotonic
 from typing import Any, TypeVar
@@ -9,16 +10,9 @@ from typing import Any, TypeVar
 import httpx
 from pydantic import BaseModel, ValidationError
 
-from agentci.adapters.codegraph import CodeGraphClient
-from agentci.adapters.opencode_support import (
-    api_contract_ready,
-    directory_headers,
-    elapsed_ms,
-    error_message,
-    load_schema,
-    model_parts,
-    models_ready,
-)
+from agentci.integrations.codegraph import CodeGraph
+from agentci.integrations.opencode.readiness import api_contract_ready, models_ready
+from agentci.integrations.opencode.schemas import load_schema
 
 T = TypeVar("T", bound=BaseModel)
 log = logging.getLogger(__name__)
@@ -28,7 +22,7 @@ class OpenCodeError(RuntimeError):
     pass
 
 
-class OpenCodeClient:
+class OpenCode:
     def __init__(
         self,
         *,
@@ -39,7 +33,7 @@ class OpenCodeClient:
         health_directory: Path,
         required_models: tuple[tuple[str, str | None], ...],
         timeout_seconds: int,
-        codegraph: CodeGraphClient | None = None,
+        codegraph: CodeGraph | None = None,
         transport: httpx.AsyncBaseTransport | None = None,
     ) -> None:
         self.schemas_dir = schemas_dir
@@ -48,8 +42,9 @@ class OpenCodeClient:
             (*model_parts(model), variant) for model, variant in required_models
         }
         self._contract_valid: bool | None = None
+        self._readiness_task: asyncio.Task[bool] | None = None
         self.timeout_seconds = timeout_seconds
-        self.codegraph = codegraph or CodeGraphClient()
+        self.codegraph = codegraph or CodeGraph()
         self._active_sessions: dict[str, Path] = {}
         self.client = httpx.AsyncClient(
             base_url=base_url.rstrip("/"),
@@ -59,11 +54,27 @@ class OpenCodeClient:
         )
 
     async def close(self) -> None:
+        if self._readiness_task is not None and not self._readiness_task.done():
+            self._readiness_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._readiness_task
+        self._readiness_task = None
         for session_id, workspace in tuple(self._active_sessions.items()):
-            await self.abort(session_id, workspace)
+            await self.abort(session_id, workspace, best_effort=True)
         await self.client.aclose()
 
     async def ready(self) -> bool:
+        task = self._readiness_task
+        if task is None:
+            task = asyncio.create_task(self._check_ready())
+            self._readiness_task = task
+        try:
+            return await asyncio.shield(task)
+        finally:
+            if task.done() and self._readiness_task is task:
+                self._readiness_task = None
+
+    async def _check_ready(self) -> bool:
         try:
             health = await self.client.get("/global/health", timeout=10)
             health.raise_for_status()
@@ -85,28 +96,6 @@ class OpenCodeClient:
         except (httpx.HTTPError, TypeError, ValueError):
             return False
 
-    async def start(
-        self,
-        *,
-        workspace: Path,
-        prompt: str,
-        model: str,
-        variant: str | None,
-        schema_name: str,
-        result_type: type[T],
-    ) -> tuple[str, T]:
-        session_id = await self.create_session(workspace, schema_name)
-        result = await self.resume(
-            session_id=session_id,
-            workspace=workspace,
-            prompt=prompt,
-            model=model,
-            variant=variant,
-            schema_name=schema_name,
-            result_type=result_type,
-        )
-        return session_id, result
-
     async def create_session(self, workspace: Path, title: str) -> str:
         response = await self._request(
             "POST",
@@ -143,7 +132,10 @@ class OpenCodeClient:
                 result_type=result_type,
             )
         except (asyncio.CancelledError, OpenCodeError):
-            await asyncio.shield(self.abort(session_id, workspace))
+            try:
+                await asyncio.shield(self.abort(session_id, workspace))
+            except OpenCodeError as exc:
+                log.warning("OpenCode failed session could not be aborted", exc_info=exc)
             raise
         finally:
             self._active_sessions.pop(session_id, None)
@@ -186,7 +178,6 @@ class OpenCodeClient:
                     json=payload,
                 )
             except httpx.TimeoutException as exc:
-                await self.abort(session_id, workspace)
                 message = f"OpenCode turn exceeded {self.timeout_seconds} seconds"
                 raise OpenCodeError(message) from exc
             info = response.get("info")
@@ -238,12 +229,40 @@ class OpenCodeClient:
             raise OpenCodeError(f"OpenCode returned an invalid response for {method} {path}")
         return payload
 
-    async def abort(self, session_id: str, workspace: Path) -> None:
+    async def abort(self, session_id: str, workspace: Path, *, best_effort: bool = False) -> None:
         try:
-            await self.client.post(
-                f"/session/{session_id}/abort",
-                headers=directory_headers(workspace),
-                timeout=10,
+            response = await self.client.post(
+                f"/session/{session_id}/abort", headers=directory_headers(workspace), timeout=10
             )
-        except httpx.HTTPError:
-            log.exception("OpenCode session could not be aborted")
+            if response.is_success or response.status_code in {404, 409}:
+                return
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            if best_effort:
+                log.warning("OpenCode session could not be aborted", exc_info=exc)
+                return
+            raise OpenCodeError(f"OpenCode session {session_id} could not be aborted") from exc
+
+
+def model_parts(model: str) -> tuple[str, str]:
+    provider, separator, model_id = model.partition("/")
+    if not separator or not provider or not model_id:
+        raise ValueError(f"OpenCode model must use provider/model format: {model}")
+    return provider, model_id
+
+
+def error_message(error: object) -> str | None:
+    if not error:
+        return None
+    if isinstance(error, dict):
+        return str(error.get("name") or error.get("message") or error)
+    return str(error)
+
+
+def elapsed_ms(started: float) -> int:
+    return round((monotonic() - started) * 1000)
+
+
+def directory_headers(workspace: Path) -> dict[str, str]:
+    return {"X-Opencode-Directory": str(workspace.resolve())}
+

src/agentci/integrations/opencode/readiness.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def api_contract_ready(document: object) -> bool:
+    if not isinstance(document, dict) or not isinstance(document.get("paths"), dict):
+        return False
+    paths = document["paths"]
+    fixed = {"/global/health": "get", "/provider": "get", "/session": "post"}
+    for path, method in fixed.items():
+        operations = paths.get(path)
+        if not isinstance(operations, dict) or method not in operations:
+            return False
+    session_paths = [
+        path
+        for path, operations in paths.items()
+        if isinstance(path, str) and isinstance(operations, dict) and path.startswith("/session/{")
+    ]
+    has_message = any(path.endswith("/message") and "post" in paths[path] for path in session_paths)
+    has_abort = any(path.endswith("/abort") and "post" in paths[path] for path in session_paths)
+    return has_message and has_abort
+
+
+def models_ready(payload: object, requirements: set[tuple[str, str, str | None]]) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    connected_value = payload.get("connected")
+    provider_values = payload.get("all")
+    if not isinstance(connected_value, list) or not all(
+        isinstance(item, str) for item in connected_value
+    ):
+        return False
+    if not isinstance(provider_values, list):
+        return False
+    connected = set(connected_value)
+    providers: dict[str, dict[str, Any]] = {}
+    for item in provider_values:
+        if not isinstance(item, dict):
+            continue
+        provider_id = item.get("id")
+        if isinstance(provider_id, str) and isinstance(item.get("models"), dict):
+            providers[provider_id] = item
+    for provider_id, model_id, variant in requirements:
+        provider = providers.get(provider_id)
+        if provider_id not in connected or not isinstance(provider, dict):
+            return False
+        model: Any = provider["models"].get(model_id)
+        if not isinstance(model, dict) or model.get("status") == "deprecated":
+            return False
+        capabilities = model.get("capabilities")
+        if not isinstance(capabilities, dict) or capabilities.get("toolcall") is not True:
+            return False
+        if variant:
+            variants = model.get("variants")
+            if not isinstance(variants, dict) or variant not in variants:
+                return False
+    return True

src/agentci/integrations/opencode/schemas.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_schema(schemas_dir: Path, name: str) -> dict[str, Any]:
+    try:
+        value = json.loads((schemas_dir / name).read_text())
+    except (OSError, ValueError) as exc:
+        raise ValueError(f"Cannot load result schema {name}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"Result schema {name} is not a JSON object")
+    return value

src/agentci/migrations/003_state_machine.sql

@@ -0,0 +1,96 @@
+PRAGMA foreign_keys=OFF;
+
+ALTER TABLE jobs RENAME TO jobs_legacy;
+
+CREATE TABLE jobs (
+    id TEXT PRIMARY KEY,
+    kind TEXT,
+    target_key TEXT NOT NULL,
+    repo_owner TEXT NOT NULL,
+    repo_name TEXT NOT NULL,
+    issue_number INTEGER NOT NULL,
+    pr_number INTEGER,
+    requester TEXT NOT NULL,
+    message TEXT,
+    comment_id INTEGER NOT NULL,
+    delivery_id TEXT NOT NULL UNIQUE,
+    receive_sequence INTEGER NOT NULL UNIQUE,
+    command_body TEXT NOT NULL,
+    workflow_id TEXT REFERENCES workflows(id),
+    status TEXT NOT NULL,
+    stage TEXT NOT NULL,
+    error TEXT,
+    runtime_session_id TEXT,
+    accepted_comment_id INTEGER,
+    started_comment_id INTEGER,
+    comment_body TEXT,
+    created_at TEXT NOT NULL,
+    started_at TEXT,
+    finished_at TEXT
+);
+
+INSERT INTO jobs (
+    id, kind, target_key, repo_owner, repo_name, issue_number, pr_number,
+    requester, message, comment_id, delivery_id, receive_sequence, command_body,
+    workflow_id, status, stage, error, runtime_session_id, accepted_comment_id,
+    started_comment_id, created_at, started_at, finished_at
+)
+SELECT j.id, j.kind, j.target_key, j.repo_owner, j.repo_name, j.issue_number,
+       j.pr_number, j.requester, j.message, j.comment_id,
+       COALESCE(d.delivery_id, 'legacy:' || j.id),
+       ROW_NUMBER() OVER (ORDER BY j.created_at, j.id),
+       '/agent ' || CASE j.kind
+           WHEN 'iterate_plan' THEN 'iterate'
+           WHEN 'iterate_implement' THEN 'iterate'
+           ELSE j.kind END || CASE WHEN j.message = '' THEN '' ELSE ' ' || j.message END,
+       j.workflow_id, j.status, j.stage, j.error, j.runtime_session_id,
+       j.accepted_comment_id, j.started_comment_id, j.created_at, j.started_at, j.finished_at
+FROM jobs_legacy j
+LEFT JOIN deliveries d ON d.comment_id = j.comment_id;
+
+CREATE TABLE job_events (
+    event_id TEXT PRIMARY KEY,
+    job_id TEXT NOT NULL REFERENCES jobs(id) DEFERRABLE INITIALLY DEFERRED,
+    event_type TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+INSERT INTO job_events(event_id, job_id, event_type, payload_json, created_at)
+SELECT 'delivery:' || delivery_id, id, 'legacy', '{}', created_at FROM jobs;
+
+CREATE TABLE listener_tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id TEXT NOT NULL REFERENCES jobs(id),
+    source_event_id TEXT NOT NULL REFERENCES job_events(event_id),
+    ordinal INTEGER NOT NULL,
+    listener TEXT NOT NULL,
+    queue TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    attempts INTEGER NOT NULL DEFAULT 0,
+    available_at TEXT NOT NULL,
+    error TEXT,
+    created_at TEXT NOT NULL,
+    started_at TEXT,
+    finished_at TEXT,
+    UNIQUE(source_event_id, listener, ordinal)
+);
+
+INSERT INTO listener_tasks(
+    job_id, source_event_id, ordinal, listener, queue, status, available_at, created_at
+)
+SELECT id, 'delivery:' || delivery_id, 0, 'execute', 'jobs', 'pending', created_at, created_at
+FROM jobs WHERE status = 'queued';
+
+INSERT INTO listener_tasks(
+    job_id, source_event_id, ordinal, listener, queue, status, available_at, created_at
+)
+SELECT id, 'delivery:' || delivery_id, 1, 'reconcile_comment', 'control', 'pending',
+       created_at, created_at
+FROM jobs WHERE status = 'queued';
+
+DROP TABLE jobs_legacy;
+CREATE INDEX idx_jobs_queue ON jobs(status, receive_sequence);
+CREATE INDEX idx_jobs_target ON jobs(target_key, status);
+CREATE INDEX idx_listener_eligible ON listener_tasks(queue, status, available_at, id);
+PRAGMA foreign_keys=ON;

src/agentci/observability/__init__.py

@@ -0,0 +1 @@
+"""Service observability configuration."""

src/agentci/observability/logging.py

@@ -15,6 +15,7 @@ LOG_FIELDS = (
     "method",
     "path",
     "status_code",
+    "error_message",
     "attempt",
     "item_count",
     "duration_ms",
@@ -37,9 +38,14 @@ class JsonFormatter(logging.Formatter):
         try:
             return json.dumps(payload, ensure_ascii=False)
         except (TypeError, ValueError):
-            payload["message"] = "Log record could not be serialized"
-            payload["exception"] = traceback.format_exc()
-            return json.dumps(payload, ensure_ascii=False)
+            fallback = {
+                "timestamp": payload["timestamp"],
+                "level": payload["level"],
+                "logger": payload["logger"],
+                "message": "Log record could not be serialized",
+                "exception": traceback.format_exc(),
+            }
+            return json.dumps(fallback, ensure_ascii=False)
 
 
 def configure_logging() -> None:

src/agentci/prompts/__init__.py

@@ -1,14 +1 @@
-from __future__ import annotations
-
-from pathlib import Path
-from string import Template
-
-
-class PromptLibrary:
-    def __init__(self, directory: Path | None = None) -> None:
-        self.directory = directory or Path(__file__).parent
-
-    def render(self, name: str, **values: str) -> str:
-        template = Template((self.directory / f"{name}.md").read_text())
-        return template.substitute(values)
-
+"""Prompt templates and structured-output contracts."""

src/agentci/prompts/library.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+from string import Template
+
+
+class PromptLibrary:
+    def __init__(self, directory: Path | None = None) -> None:
+        self.directory = directory or Path(__file__).parent
+
+    def render(self, name: str, **values: str) -> str:
+        template = Template((self.directory / f"{name}.md").read_text())
+        return template.substitute(values)
+
+    @property
+    def schemas_dir(self) -> Path:
+        return self.directory / "schemas"

src/agentci/worker.py

@@ -1,190 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-from contextlib import suppress
-from pathlib import Path
-
-from agentci.adapters.gitea import GiteaClient
-from agentci.adapters.opencode import OpenCodeClient
-from agentci.adapters.storage import Storage
-from agentci.domain.models import Job, JobStatus
-from agentci.workflows.common import JobRejected
-from agentci.workflows.dispatcher import Dispatcher
-
-log = logging.getLogger(__name__)
-
-
-class Worker:
-    def __init__(
-        self,
-        *,
-        storage: Storage,
-        gitea: GiteaClient,
-        opencode: OpenCodeClient,
-        dispatcher: Dispatcher,
-        poll_seconds: float,
-        workspaces_dir: Path,
-    ) -> None:
-        self.storage = storage
-        self.gitea = gitea
-        self.opencode = opencode
-        self.dispatcher = dispatcher
-        self.poll_seconds = poll_seconds
-        self.workspaces_dir = workspaces_dir
-
-    async def run(self, stop: asyncio.Event) -> None:
-        log.info("worker started", extra={"operation": "worker.run"})
-        await self._report_interrupted()
-        try:
-            while not stop.is_set():
-                if not await self.opencode.ready():
-                    log.warning(
-                        "worker waiting for OpenCode provider authentication",
-                        extra={"operation": "worker.poll"},
-                    )
-                    await self._wait(stop)
-                    continue
-                job = await self.storage.claim_next()
-                if job is None:
-                    await self._wait(stop)
-                    continue
-                await self._run_job(job)
-        except Exception:
-            log.exception("worker stopped unexpectedly", extra={"operation": "worker.run"})
-            raise
-        finally:
-            log.info("worker stopped", extra={"operation": "worker.run"})
-
-    async def _run_job(self, job: Job) -> None:
-        extra = {"job_id": job.id, "target": job.target_key}
-        log.info("job started", extra=extra)
-        try:
-            if job.accepted_comment_id is None:
-                job.accepted_comment_id = await self.gitea.create_comment(
-                    job.repo_owner,
-                    job.repo_name,
-                    job.issue_number,
-                    f"Agent job `{job.id}` started (`{job.kind}`).",
-                )
-                await self.storage.set_job_comment(
-                    job.id, "accepted_comment_id", job.accepted_comment_id
-                )
-            else:
-                await self.gitea.update_comment(
-                    job.repo_owner,
-                    job.repo_name,
-                    job.accepted_comment_id,
-                    f"Agent job `{job.id}` started (`{job.kind}`).",
-                )
-            await self.dispatcher.dispatch(job)
-        except JobRejected as exc:
-            await self._safe_update_job(
-                job, status=JobStatus.REJECTED, stage="rejected", error=str(exc)
-            )
-            await self._safe_job_comment(job, f"Agent job `{job.id}` was rejected: {exc}")
-            log.info("job rejected", extra={**extra, "stage": "rejected"})
-        except Exception as exc:
-            failed_stage = await self._safe_job_stage(job)
-            await self._safe_update_job(
-                job, status=JobStatus.FAILED, stage="failed", error=_safe_error(exc)
-            )
-            await self._safe_fail_workflow(job)
-            await self._safe_job_comment(
-                job,
-                f"Agent job `{job.id}` failed during `{failed_stage}`: {_safe_error(exc)}",
-            )
-            log.exception("job failed", extra={**extra, "stage": failed_stage})
-        else:
-            await self._safe_update_job(
-                job, status=JobStatus.SUCCEEDED, stage="completed"
-            )
-            log.info("job completed", extra=extra)
-
-    async def _report_interrupted(self) -> None:
-        jobs = await self.storage.recover_running()
-        if jobs:
-            log.warning(
-                "recovering interrupted jobs",
-                extra={"operation": "worker.recover", "item_count": len(jobs)},
-            )
-        for job in jobs:
-            await self._abort_job_sessions(job)
-            await self._safe_fail_workflow(job)
-            await self._safe_job_comment(
-                job,
-                f"Agent job `{job.id}` failed because the service restarted during execution.",
-            )
-
-    async def _abort_job_sessions(self, job: Job) -> None:
-        sessions: set[tuple[str, Path]] = set()
-        workflow = None
-        if job.workflow_id:
-            workflow = await self.storage.get_workflow(job.workflow_id)
-        if workflow is not None:
-            sessions.update(
-                (session_id, workflow.workspace_path)
-                for session_id in (
-                    workflow.primary_session_id,
-                    workflow.reviewer_session_id,
-                )
-                if session_id
-            )
-        elif job.runtime_session_id:
-            workspace = self.workspaces_dir / f"fix-{job.id}" / "repo"
-            sessions.add((job.runtime_session_id, workspace))
-        for session_id, workspace in sessions:
-            await self.opencode.abort(session_id, workspace)
-
-    async def _safe_job_comment(self, job: Job, body: str) -> None:
-        try:
-            if job.accepted_comment_id is None:
-                job.accepted_comment_id = await self.gitea.create_comment(
-                    job.repo_owner, job.repo_name, job.issue_number, body
-                )
-                await self.storage.set_job_comment(
-                    job.id, "accepted_comment_id", job.accepted_comment_id
-                )
-            else:
-                await self.gitea.update_comment(
-                    job.repo_owner, job.repo_name, job.accepted_comment_id, body
-                )
-        except Exception:
-            log.exception("could not publish job status", extra={"job_id": job.id})
-
-    async def _safe_job_stage(self, job: Job) -> str:
-        try:
-            return await self.storage.job_stage(job.id)
-        except Exception:
-            log.exception("could not read failed job stage", extra={"job_id": job.id})
-            return job.stage or "unknown"
-
-    async def _safe_update_job(
-        self,
-        job: Job,
-        *,
-        status: JobStatus,
-        stage: str,
-        error: str | None = None,
-    ) -> None:
-        try:
-            await self.storage.update_job(
-                job.id, status=status, stage=stage, error=error
-            )
-        except Exception:
-            log.exception("could not persist job status", extra={"job_id": job.id})
-
-    async def _safe_fail_workflow(self, job: Job) -> None:
-        try:
-            await self.storage.fail_job_workflow(job.id)
-        except Exception:
-            log.exception("could not mark workflow failed", extra={"job_id": job.id})
-
-    async def _wait(self, stop: asyncio.Event) -> None:
-        with suppress(TimeoutError):
-            await asyncio.wait_for(stop.wait(), timeout=self.poll_seconds)
-
-
-def _safe_error(error: Exception) -> str:
-    message = " ".join(str(error).split())
-    return f"{type(error).__name__}: {message}"[:1000]

src/agentci/workflows/__init__.py

@@ -1 +1 @@
-"""OpenCode workflow orchestration."""
+"""Functional workflow orchestration."""

src/agentci/workflows/change_set.py

@@ -1,56 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-from agentci.domain.models import AgentResult, Job
-from agentci.workflows.common import Dependencies, JobRejected
-
-
-class ChangeSet:
-    def __init__(self, dependencies: Dependencies) -> None:
-        self.deps = dependencies
-
-    async def commit_and_push(
-        self,
-        job: Job,
-        workspace: Path,
-        branch: str,
-        result: AgentResult,
-        *,
-        set_upstream: bool,
-        commit_prefix: str,
-    ) -> str:
-        await self.deps.storage.update_job(job.id, stage="validating changes")
-        if not await self.deps.git.has_changes(workspace):
-            raise JobRejected("OpenCode completed without producing any file changes.")
-        await self.deps.git.diff_check(workspace)
-        title = _commit_title(result.summary_markdown)
-        await self.deps.storage.update_job(job.id, stage="committing changes")
-        sha = await self.deps.git.commit(workspace, f"{commit_prefix}: {title}")
-        await self.deps.storage.update_job(job.id, stage="pushing changes")
-        await self.deps.git.push(workspace, branch, set_upstream=set_upstream)
-        return sha
-
-
-def pull_request_body(issue_number: int, result: AgentResult) -> str:
-    tests = "\n".join(f"- {item}" for item in result.tests) or "- Not reported"
-    return (
-        f"Closes #{issue_number}\n\n"
-        f"## Implementation\n\n{result.summary_markdown}\n\n"
-        f"## Validation\n\n{tests}\n\n"
-        "_Created by Agent CI._"
-    )
-
-
-def result_comment(result: AgentResult, *, sha: str | None = None) -> str:
-    tests = "\n".join(f"- {item}" for item in result.tests) or "- Not reported"
-    commit = f"\n\nCommit: `{sha}`" if sha else ""
-    return f"## Agent result\n\n{result.summary_markdown}\n\n## Validation\n\n{tests}{commit}"
-
-
-def _commit_title(markdown: str) -> str:
-    for line in markdown.splitlines():
-        value = line.strip().lstrip("#").strip()
-        if value:
-            return value[:72]
-    return "apply requested changes"

src/agentci/workflows/code_review.py

@@ -1,101 +0,0 @@
-from __future__ import annotations
-
-from agentci.domain.models import AgentResult, Job, ReviewReport, Workflow
-from agentci.workflows.common import (
-    Dependencies,
-    report_for_prompt,
-    report_json,
-    required_session,
-)
-
-
-class CodeReviewLoop:
-    def __init__(self, dependencies: Dependencies) -> None:
-        self.deps = dependencies
-
-    async def run(
-        self,
-        job: Job,
-        workflow: Workflow,
-        issue_context: str,
-        plan: str,
-        result: AgentResult,
-    ) -> tuple[AgentResult, ReviewReport]:
-        report = ReviewReport(summary="", findings=[])
-        for round_index in range(self.deps.settings.implement_review_rounds):
-            await self.deps.storage.update_job(
-                job.id,
-                stage=f"reviewing implementation {round_index + 1}/"
-                f"{self.deps.settings.implement_review_rounds}",
-            )
-            report = await self.once(
-                workflow,
-                issue_context=issue_context,
-                plan=plan,
-                pull_context=(
-                    "The proposed pull request is the current uncommitted working-tree diff. "
-                    "Review only that diff."
-                ),
-            )
-            workflow.artifact = result.model_dump_json()
-            workflow.review_json = report_json(report)
-            await self.deps.storage.update_workflow(workflow)
-            if not report.has_serious_findings:
-                break
-            if round_index == self.deps.settings.implement_review_rounds - 1:
-                break
-            prompt = self.deps.prompts.render(
-                "implementation_revision",
-                review=report_for_prompt(workflow.review_json),
-                development_environment=self.deps.development.description,
-            )
-            result = await self.deps.opencode.resume(
-                session_id=required_session(workflow.primary_session_id),
-                prompt=prompt,
-                model=self.deps.settings.implement_model,
-                variant=self.deps.settings.implement_variant,
-                workspace=workflow.workspace_path,
-                schema_name="agent_result.json",
-                result_type=AgentResult,
-            )
-        return result, report
-
-    async def once(
-        self,
-        workflow: Workflow,
-        *,
-        issue_context: str,
-        plan: str,
-        pull_context: str,
-    ) -> ReviewReport:
-        prompt = self.deps.prompts.render(
-            "implementation_review",
-            issue_context=issue_context,
-            artifact=plan,
-            pull_context=pull_context,
-        )
-        if workflow.reviewer_session_id:
-            return await self.deps.opencode.resume(
-                session_id=workflow.reviewer_session_id,
-                prompt=prompt,
-                model=self.deps.settings.implement_model,
-                variant=self.deps.settings.implement_variant,
-                workspace=workflow.workspace_path,
-                schema_name="review.json",
-                result_type=ReviewReport,
-            )
-        session_id = await self.deps.opencode.create_session(
-            workflow.workspace_path, "implementation-review"
-        )
-        workflow.reviewer_session_id = session_id
-        await self.deps.storage.update_workflow(workflow)
-        report = await self.deps.opencode.resume(
-            session_id=session_id,
-            workspace=workflow.workspace_path,
-            prompt=prompt,
-            model=self.deps.settings.implement_model,
-            variant=self.deps.settings.implement_variant,
-            schema_name="review.json",
-            result_type=ReviewReport,
-        )
-        return report

src/agentci/workflows/common.py

@@ -1,79 +0,0 @@
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass
-
-from agentci.adapters.development import DevelopmentEnvironment
-from agentci.adapters.git import GitClient
-from agentci.adapters.gitea import GiteaClient
-from agentci.adapters.opencode import OpenCodeClient
-from agentci.adapters.storage import Storage
-from agentci.config import Settings
-from agentci.domain.models import Job, ReviewReport
-from agentci.prompts import PromptLibrary
-from agentci.workflows.context import ContextBuilder
-
-
-class JobRejected(RuntimeError):
-    """A safe, expected workflow rejection to publish to the requester."""
-
-
-def required_session(value: str | None) -> str:
-    if value is None:
-        raise RuntimeError("Expected a persisted OpenCode session ID")
-    return value
-
-
-@dataclass(frozen=True)
-class Dependencies:
-    settings: Settings
-    storage: Storage
-    gitea: GiteaClient
-    git: GitClient
-    opencode: OpenCodeClient
-    prompts: PromptLibrary
-    context: ContextBuilder
-    development: DevelopmentEnvironment
-
-
-def review_markdown(report: ReviewReport) -> str:
-    if not report.findings:
-        return ""
-    lines = ["## Remaining review findings", "", report.summary]
-    for finding in report.findings:
-        location = f" — `{finding.location}`" if finding.location else ""
-        lines.extend(
-            [
-                "",
-                f"### {finding.severity.value.upper()}: {finding.title}{location}",
-                finding.detail,
-                "",
-                f"Recommendation: {finding.recommendation}",
-            ]
-        )
-    return "\n".join(lines)
-
-
-def report_json(report: ReviewReport) -> str:
-    return report.model_dump_json()
-
-
-def report_for_prompt(report_json_value: str | None) -> str:
-    if not report_json_value:
-        return "(none)"
-    try:
-        return json.dumps(json.loads(report_json_value), indent=2)
-    except json.JSONDecodeError:
-        return report_json_value
-
-
-def agent_comment(kind: str, workflow_id: str, body: str) -> str:
-    return f"<!-- agentci:{kind} workflow={workflow_id} -->\n{body}"
-
-
-async def update_job_comment(deps: Dependencies, job: Job, body: str) -> None:
-    if job.accepted_comment_id is None:
-        raise RuntimeError("Expected a persisted Gitea job comment ID")
-    await deps.gitea.update_comment(
-        job.repo_owner, job.repo_name, job.accepted_comment_id, body
-    )

src/agentci/workflows/context.py

@@ -1,81 +1,104 @@
 from __future__ import annotations
 
+import asyncio
 from typing import Any
 
-from agentci.adapters.gitea import GiteaClient
-from agentci.adapters.gitea_models import CommentInfo, PullRequestInfo
-from agentci.adapters.storage import Storage
+from agentci.engine.repository import Repository
+from agentci.integrations.gitea.client import Gitea
+from agentci.integrations.gitea.models import CommentInfo, PullRequestInfo
 
 
-class ContextBuilder:
-    def __init__(self, gitea: GiteaClient, storage: Storage) -> None:
-        self.gitea = gitea
-        self.storage = storage
+async def build_issue_context(
+    gitea: Gitea,
+    repository: Repository,
+    owner: str,
+    repo: str,
+    number: int,
+) -> str:
+    issue, comments, operational = await asyncio.gather(
+        gitea.issue(owner, repo, number),
+        gitea.issue_comments(owner, repo, number),
+        repository.operational_comment_ids(owner, repo, number),
+    )
+    discussion = "\n\n".join(
+        _format_comment(comment) for comment in comments if comment.id not in operational
+    )
+    return (
+        f"Repository: {owner}/{repo}\n"
+        f"Issue: #{number} \u2014 {issue.title}\n"
+        f"State: {issue.state}\n\n"
+        f"## Issue body\n{issue.body or '(empty)'}\n\n"
+        f"## Discussion\n{discussion or '(none)'}"
+    )
 
-    async def issue_context(self, owner: str, repo: str, number: int) -> str:
-        issue = await self.gitea.issue(owner, repo, number)
-        comments = await self.gitea.issue_comments(owner, repo, number)
-        operational = await self.storage.operational_comment_ids(owner, repo, number)
-        discussion = "\n\n".join(
-            _format_comment(comment) for comment in comments if comment.id not in operational
+
+async def build_pull_request_context(
+    gitea: Gitea,
+    owner: str,
+    repo: str,
+    number: int,
+) -> tuple[PullRequestInfo, str]:
+    pull, timeline, reviews, commits = await asyncio.gather(
+        gitea.pull_request(owner, repo, number),
+        gitea.issue_comments(owner, repo, number),
+        gitea.pull_reviews(owner, repo, number),
+        gitea.pull_commits(owner, repo, number),
+    )
+    review_text = await _format_reviews(gitea, owner, repo, number, reviews)
+    timeline_text = "\n\n".join(_format_comment(item) for item in timeline)
+    commit_text = "\n".join(
+        f"- {item.get('sha', '')[:12]} {item.get('commit', {}).get('message', '')}"
+        for item in commits
+    )
+    context = (
+        f"Repository: {owner}/{repo}\n"
+        f"Pull request: #{number} \u2014 {pull.title}\n"
+        f"State: {pull.state}; merged: {pull.merged}\n"
+        f"Base: {pull.base_branch}; head: {pull.head_owner}/{pull.head_repo}:"
+        f"{pull.head_branch} @ {pull.head_sha}\n\n"
+        f"## Pull request body\n{pull.body or '(empty)'}\n\n"
+        f"## Commits\n{commit_text or '(none)'}\n\n"
+        f"## Timeline discussion\n{timeline_text or '(none)'}\n\n"
+        f"## Formal and inline reviews\n{review_text or '(none)'}"
+    )
+    return pull, context
+
+
+async def _format_reviews(
+    gitea: Gitea,
+    owner: str,
+    repo: str,
+    number: int,
+    reviews: list[dict[str, Any]],
+) -> str:
+    details = [
+        (
+            int(review["id"]),
+            review.get("user", {}).get("login", "unknown"),
+            review.get("state", "unknown"),
+            review.get("body") or "(empty)",
         )
-        return (
-            f"Repository: {owner}/{repo}\n"
-            f"Issue: #{number} — {issue.title}\n"
-            f"State: {issue.state}\n\n"
-            f"## Issue body\n{issue.body or '(empty)'}\n\n"
-            f"## Discussion\n{discussion or '(none)'}"
+        for review in reviews
+    ]
+    comment_groups = await asyncio.gather(
+        *(
+            gitea.review_comments(owner, repo, number, review_id)
+            for review_id, _, _, _ in details
         )
-
-    async def pull_request_context(
-        self, owner: str, repo: str, number: int
-    ) -> tuple[PullRequestInfo, str]:
-        pull = await self.gitea.pull_request(owner, repo, number)
-        timeline = await self.gitea.issue_comments(owner, repo, number)
-        reviews = await self.gitea.pull_reviews(owner, repo, number)
-        commits = await self.gitea.pull_commits(owner, repo, number)
-        review_text = await self._format_reviews(owner, repo, number, reviews)
-        timeline_text = "\n\n".join(_format_comment(item) for item in timeline)
-        commit_text = "\n".join(
-            f"- {item.get('sha', '')[:12]} {item.get('commit', {}).get('message', '')}"
-            for item in commits
-        )
-        context = (
-            f"Repository: {owner}/{repo}\n"
-            f"Pull request: #{number} — {pull.title}\n"
-            f"State: {pull.state}; merged: {pull.merged}\n"
-            f"Base: {pull.base_branch}; head: {pull.head_owner}/{pull.head_repo}:"
-            f"{pull.head_branch} @ {pull.head_sha}\n\n"
-            f"## Pull request body\n{pull.body or '(empty)'}\n\n"
-            f"## Commits\n{commit_text or '(none)'}\n\n"
-            f"## Timeline discussion\n{timeline_text or '(none)'}\n\n"
-            f"## Formal and inline reviews\n{review_text or '(none)'}"
-        )
-        return pull, context
-
-    async def _format_reviews(
-        self,
-        owner: str,
-        repo: str,
-        number: int,
-        reviews: list[dict[str, Any]],
-    ) -> str:
-        sections: list[str] = []
-        for review in reviews:
-            review_id = int(review["id"])
-            author = review.get("user", {}).get("login", "unknown")
-            state = review.get("state", "unknown")
-            body = review.get("body") or "(empty)"
-            lines = [f"### Review {review_id} by {author} ({state})\n{body}"]
-            for comment in await self.gitea.review_comments(owner, repo, number, review_id):
-                path = comment.get("path") or "unknown file"
-                line = comment.get("new_position") or comment.get("old_position") or "?"
-                text = comment.get("body") or ""
-                lines.append(f"- `{path}:{line}`: {text}")
-            sections.append("\n".join(lines))
-        return "\n\n".join(sections)
+    )
+    sections: list[str] = []
+    for (review_id, author, state, body), comments in zip(
+        details, comment_groups, strict=True
+    ):
+        lines = [f"### Review {review_id} by {author} ({state})\n{body}"]
+        for comment in comments:
+            path = comment.get("path") or "unknown file"
+            line = comment.get("new_position") or comment.get("old_position") or "?"
+            text = comment.get("body") or ""
+            lines.append(f"- `{path}:{line}`: {text}")
+        sections.append("\n".join(lines))
+    return "\n\n".join(sections)
 
 
 def _format_comment(comment: CommentInfo) -> str:
     return f"### {comment.author} at {comment.created_at}\n{comment.body}"
-

src/agentci/workflows/dispatch.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import logging
+
+from agentci.engine.model import Job, JobKind
+from agentci.engine.run import JobRun
+from agentci.workflows.implementation import implement
+from agentci.workflows.plan import create_plan, discuss_plan, iterate_plan
+from agentci.workflows.pull_request import fix_pull_request, iterate_implementation
+from agentci.workflows.services import WorkflowServices
+
+log = logging.getLogger(__name__)
+
+
+async def dispatch(job: Job, run: JobRun, services: WorkflowServices) -> str:
+    if job.kind is None:
+        raise RuntimeError("Cannot dispatch an unparsed command")
+    extra = {
+        "operation": "workflow.dispatch",
+        "job_id": job.id,
+        "target": job.target_key,
+        "stage": job.kind.value,
+    }
+    log.info("workflow dispatch started", extra=extra)
+    try:
+        match job.kind:
+            case JobKind.PLAN:
+                body = await create_plan(job, run, services)
+            case JobKind.DISCUSS:
+                body = await discuss_plan(job, run, services)
+            case JobKind.ITERATE_PLAN:
+                body = await iterate_plan(job, run, services)
+            case JobKind.IMPLEMENT:
+                body = await implement(job, run, services)
+            case JobKind.ITERATE_IMPLEMENT:
+                body = await iterate_implementation(job, run, services)
+            case JobKind.FIX:
+                body = await fix_pull_request(job, run, services)
+            case _:
+                raise KeyError(job.kind)
+    except Exception:
+        log.exception("workflow dispatch failed", extra=extra)
+        raise
+    log.info("workflow dispatch completed", extra=extra)
+    return body

src/agentci/workflows/dispatcher.py

@@ -1,40 +0,0 @@
-from __future__ import annotations
-
-import logging
-
-from agentci.domain.models import Job, JobKind
-from agentci.workflows.common import Dependencies
-from agentci.workflows.implement import ImplementWorkflow
-from agentci.workflows.plan import PlanWorkflow
-from agentci.workflows.pull_request import PullRequestWorkflow
-
-log = logging.getLogger(__name__)
-
-
-class Dispatcher:
-    def __init__(self, dependencies: Dependencies) -> None:
-        plan = PlanWorkflow(dependencies)
-        pull_request = PullRequestWorkflow(dependencies)
-        self.handlers = {
-            JobKind.PLAN: plan.plan,
-            JobKind.DISCUSS: plan.discuss,
-            JobKind.ITERATE_PLAN: plan.iterate,
-            JobKind.IMPLEMENT: ImplementWorkflow(dependencies).run,
-            JobKind.ITERATE_IMPLEMENT: pull_request.iterate,
-            JobKind.FIX: pull_request.fix,
-        }
-
-    async def dispatch(self, job: Job) -> None:
-        extra = {
-            "operation": "workflow.dispatch",
-            "job_id": job.id,
-            "target": job.target_key,
-            "stage": job.kind.value,
-        }
-        log.info("workflow dispatch started", extra=extra)
-        try:
-            await self.handlers[job.kind](job)
-        except Exception:
-            log.exception("workflow dispatch failed", extra=extra)
-            raise
-        log.info("workflow dispatch completed", extra=extra)

src/agentci/workflows/implement.py

@@ -1,153 +0,0 @@
-from __future__ import annotations
-
-from uuid import uuid4
-
-from agentci.domain.models import (
-    AgentResult,
-    Job,
-    Workflow,
-    WorkflowKind,
-    WorkflowStatus,
-)
-from agentci.workflows.change_set import ChangeSet, pull_request_body, result_comment
-from agentci.workflows.code_review import CodeReviewLoop
-from agentci.workflows.common import (
-    Dependencies,
-    JobRejected,
-    agent_comment,
-    report_json,
-    review_markdown,
-    update_job_comment,
-)
-
-
-class ImplementWorkflow:
-    def __init__(self, dependencies: Dependencies) -> None:
-        self.deps = dependencies
-        self.review = CodeReviewLoop(dependencies)
-        self.changes = ChangeSet(dependencies)
-
-    async def run(self, job: Job) -> None:
-        await self._reject_duplicate(job)
-        repository = await self.deps.gitea.repository(job.repo_owner, job.repo_name)
-        issue = await self.deps.gitea.issue(job.repo_owner, job.repo_name, job.issue_number)
-        workflow_id = str(uuid4())
-        branch = (
-            f"{self.deps.settings.branch_prefix}/issue-{job.issue_number}-"
-            f"{workflow_id[:8]}"
-        )
-        workspace = self.deps.settings.workspaces_dir / workflow_id / "repo"
-        await self.deps.storage.update_job(job.id, stage="cloning")
-        base_sha = await self.deps.git.clone(
-            job.repo_owner,
-            job.repo_name,
-            repository.default_branch,
-            workspace,
-        )
-        await self.deps.git.create_branch(workspace, branch)
-        workflow = Workflow(
-            id=workflow_id,
-            kind=WorkflowKind.IMPLEMENT,
-            repo_owner=job.repo_owner,
-            repo_name=job.repo_name,
-            issue_number=job.issue_number,
-            workspace_path=workspace,
-            base_sha=base_sha,
-            branch=branch,
-        )
-        await self.deps.storage.create_workflow(workflow)
-        job.workflow_id = workflow.id
-        await self.deps.storage.update_job(
-            job.id, workflow_id=workflow.id, stage="installing development environment"
-        )
-        await self.deps.development.prepare(workspace)
-        await self.deps.storage.update_job(
-            job.id, workflow_id=workflow.id, stage="implementing"
-        )
-        context = await self.deps.context.issue_context(
-            job.repo_owner, job.repo_name, job.issue_number
-        )
-        plan = await self.deps.storage.latest_workflow(
-            job.repo_owner, job.repo_name, job.issue_number, WorkflowKind.PLAN
-        )
-        prompt = self.deps.prompts.render(
-            "implement_initial",
-            context=context,
-            artifact=plan.artifact if plan and plan.artifact else "(no canonical plan)",
-            request=job.message or "(no additional request)",
-            development_environment=self.deps.development.description,
-        )
-        session_id = await self.deps.opencode.create_session(workspace, "implementation")
-        workflow.primary_session_id = session_id
-        await self.deps.storage.update_workflow(workflow)
-        await self.deps.storage.update_job(job.id, runtime_session_id=session_id)
-        result = await self.deps.opencode.resume(
-            session_id=session_id,
-            workspace=workspace,
-            prompt=prompt,
-            model=self.deps.settings.implement_model,
-            variant=self.deps.settings.implement_variant,
-            schema_name="agent_result.json",
-            result_type=AgentResult,
-        )
-        workflow.artifact = result.model_dump_json()
-        await self.deps.storage.update_workflow(workflow)
-        result, report = await self.review.run(
-            job,
-            workflow,
-            context,
-            plan.artifact if plan and plan.artifact else "(no canonical plan)",
-            result,
-        )
-        sha = await self.changes.commit_and_push(
-            job,
-            workspace,
-            branch,
-            result,
-            set_upstream=True,
-            commit_prefix="agent",
-        )
-        await self.deps.storage.update_job(job.id, stage="creating pull request")
-        pull = await self.deps.gitea.create_pull_request(
-            job.repo_owner,
-            job.repo_name,
-            title=f"Agent: {issue.title}",
-            body=pull_request_body(job.issue_number, result),
-            head=branch,
-            base=repository.default_branch,
-        )
-        workflow.pr_number = pull.number
-        workflow.artifact = result.model_dump_json()
-        workflow.review_json = report_json(report)
-        workflow.status = WorkflowStatus.COMPLETED
-        await self.deps.storage.update_workflow(workflow)
-        pull_url = (
-            f"{self.deps.settings.gitea_url}/{job.repo_owner}/"
-            f"{job.repo_name}/pulls/{pull.number}"
-        )
-        body = f"Pull request created: {pull_url}\n\n{result_comment(result, sha=sha)}"
-        body = agent_comment("implementation", workflow.id, body)
-        remaining = review_markdown(report)
-        if remaining:
-            body = f"{body}\n\n{remaining}"
-        await update_job_comment(self.deps, job, body)
-
-    async def _reject_duplicate(self, job: Job) -> None:
-        workflows = await self.deps.storage.implementation_workflows(
-            job.repo_owner, job.repo_name, job.issue_number
-        )
-        for workflow in workflows:
-            if workflow.pr_number is None:
-                continue
-            pull = await self.deps.gitea.pull_request(
-                job.repo_owner, job.repo_name, workflow.pr_number
-            )
-            if pull.is_open:
-                raise JobRejected(
-                    f"Agent PR #{pull.number} is already open. Use `/agent iterate` "
-                    "on that pull request."
-                )
-            if pull.merged:
-                raise JobRejected(
-                    f"Agent PR #{pull.number} has already been merged for this issue."
-                )

src/agentci/workflows/implementation.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+from uuid import uuid4
+
+from agentci.engine.model import Job, Workflow, WorkflowKind, WorkflowStatus
+from agentci.engine.run import JobRun
+from agentci.workflows.context import build_issue_context
+from agentci.workflows.model import AgentResult
+from agentci.workflows.render import (
+    JobRejected,
+    commit_title,
+    final_comment,
+    pull_request_body,
+    result_comment,
+)
+from agentci.workflows.review import review_implementation_loop
+from agentci.workflows.services import WorkflowServices
+
+
+async def implement(job: Job, run: JobRun, services: WorkflowServices) -> str:
+    await _reject_duplicate(job, services)
+    default_branch = await services.gitea.default_branch(job.repo_owner, job.repo_name)
+    issue = await services.gitea.issue(job.repo_owner, job.repo_name, job.issue_number)
+    workflow_id = str(uuid4())
+    branch = (
+        f"{services.settings.branch_prefix}/issue-{job.issue_number}-"
+        f"{workflow_id[:8]}"
+    )
+    workspace = services.settings.workspaces_dir / workflow_id / "repo"
+
+    await run.stage("cloning")
+    base_sha = await services.git.clone(
+        job.repo_owner,
+        job.repo_name,
+        default_branch,
+        workspace,
+    )
+    await services.git.create_branch(workspace, branch)
+    workflow = Workflow(
+        id=workflow_id,
+        kind=WorkflowKind.IMPLEMENT,
+        repo_owner=job.repo_owner,
+        repo_name=job.repo_name,
+        issue_number=job.issue_number,
+        workspace_path=workspace,
+        base_sha=base_sha,
+        branch=branch,
+    )
+    await run.create_workflow(workflow, "installing development environment")
+    await services.development.prepare(workspace)
+
+    await run.stage("implementing")
+    context = await build_issue_context(
+        services.gitea,
+        services.repository,
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+    )
+    plan = await services.repository.latest_workflow(
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+        WorkflowKind.PLAN,
+    )
+    plan_artifact = plan.artifact if plan and plan.artifact else "(no canonical plan)"
+    prompt = services.prompts.render(
+        "implement_initial",
+        context=context,
+        artifact=plan_artifact,
+        request=job.message or "(no additional request)",
+        development_environment=services.development.description,
+    )
+    session_id = await services.opencode.create_session(workspace, "implementation")
+    workflow = replace(workflow, primary_session_id=session_id)
+    await services.repository.save_workflow(workflow)
+    await run.link_session(session_id)
+
+    result = await services.opencode.resume(
+        session_id=session_id,
+        workspace=workspace,
+        prompt=prompt,
+        model=services.settings.implement_model,
+        variant=services.settings.implement_variant,
+        schema_name="agent_result.json",
+        result_type=AgentResult,
+    )
+    workflow = replace(workflow, artifact=result.model_dump_json())
+    await services.repository.save_workflow(workflow)
+
+    workflow, result, report = await review_implementation_loop(
+        workflow,
+        context,
+        plan_artifact,
+        result,
+        run,
+        services,
+    )
+    sha = await commit_and_push(
+        run,
+        services,
+        workspace,
+        branch,
+        result,
+        set_upstream=True,
+        commit_prefix="agent",
+    )
+
+    await run.stage("creating pull request")
+    pull = await services.gitea.create_pull_request(
+        job.repo_owner,
+        job.repo_name,
+        title=f"Agent: {issue.title}",
+        body=pull_request_body(job.issue_number, result),
+        head=branch,
+        base=default_branch,
+    )
+    workflow = replace(
+        workflow,
+        pr_number=pull.number,
+        artifact=result.model_dump_json(),
+        review_json=report.model_dump_json(),
+        status=WorkflowStatus.COMPLETED,
+    )
+    await services.repository.save_workflow(workflow)
+
+    pull_url = (
+        f"{services.settings.gitea_url}/{job.repo_owner}/"
+        f"{job.repo_name}/pulls/{pull.number}"
+    )
+    body = f"Pull request created: {pull_url}\n\n{result_comment(result, sha=sha)}"
+    return final_comment("implementation", workflow.id, body, report)
+
+
+async def commit_and_push(
+    run: JobRun,
+    services: WorkflowServices,
+    workspace: Path,
+    branch: str,
+    result: AgentResult,
+    *,
+    set_upstream: bool,
+    commit_prefix: str,
+) -> str:
+    await run.stage("validating changes")
+    if not await services.git.has_changes(workspace):
+        raise JobRejected("OpenCode completed without producing any file changes.")
+    await services.git.diff_check(workspace)
+    title = commit_title(result.summary_markdown)
+    await run.stage("committing changes")
+    sha = await services.git.commit(workspace, f"{commit_prefix}: {title}")
+    await run.stage("pushing changes")
+    await services.git.push(workspace, branch, set_upstream=set_upstream)
+    return sha
+
+
+async def _reject_duplicate(job: Job, services: WorkflowServices) -> None:
+    workflows = await services.repository.implementation_workflows(
+        job.repo_owner, job.repo_name, job.issue_number
+    )
+    for workflow in workflows:
+        if workflow.pr_number is None:
+            continue
+        pull = await services.gitea.pull_request(
+            job.repo_owner, job.repo_name, workflow.pr_number
+        )
+        if pull.is_open:
+            raise JobRejected(
+                f"Agent PR #{pull.number} is already open. Use `/agent iterate` "
+                "on that pull request."
+            )
+        if pull.merged:
+            raise JobRejected(
+                f"Agent PR #{pull.number} has already been merged for this issue."
+            )

src/agentci/workflows/model.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class ReviewSeverity(StrEnum):
+    BLOCKING = "blocking"
+    MAJOR = "major"
+    MINOR = "minor"
+
+
+class PlanArtifact(BaseModel):
+    plan_markdown: str = Field(min_length=1)
+
+
+class DiscussionReply(BaseModel):
+    markdown: str = Field(min_length=1)
+
+
+class AgentResult(BaseModel):
+    summary_markdown: str = Field(min_length=1)
+    tests: list[str] = Field(default_factory=list)
+
+
+class ReviewFinding(BaseModel):
+    severity: ReviewSeverity
+    title: str
+    detail: str
+    location: str | None = None
+    recommendation: str
+
+
+class ReviewReport(BaseModel):
+    summary: str
+    findings: list[ReviewFinding] = Field(default_factory=list)
+
+    @property
+    def has_serious_findings(self) -> bool:
+        return any(
+            finding.severity in {ReviewSeverity.BLOCKING, ReviewSeverity.MAJOR}
+            for finding in self.findings
+        )

src/agentci/workflows/plan.py

@@ -1,242 +1,189 @@
 from __future__ import annotations
 
+from dataclasses import replace
 from uuid import uuid4
 
-from agentci.domain.models import (
-    DiscussionReply,
+from agentci.engine.model import (
     Job,
-    PlanArtifact,
-    ReviewReport,
     Workflow,
     WorkflowKind,
     WorkflowStatus,
 )
-from agentci.workflows.common import (
-    Dependencies,
+from agentci.engine.run import JobRun
+from agentci.workflows.context import build_issue_context
+from agentci.workflows.model import DiscussionReply, PlanArtifact
+from agentci.workflows.render import (
     JobRejected,
     agent_comment,
+    final_comment,
     report_for_prompt,
-    report_json,
-    required_session,
-    review_markdown,
-    update_job_comment,
 )
+from agentci.workflows.review import review_plan_loop, review_plan_once
+from agentci.workflows.services import WorkflowServices
 
 
-class PlanWorkflow:
-    def __init__(self, dependencies: Dependencies) -> None:
-        self.deps = dependencies
+async def create_plan(job: Job, run: JobRun, services: WorkflowServices) -> str:
+    default_branch = await services.gitea.default_branch(job.repo_owner, job.repo_name)
+    workflow_id = str(uuid4())
+    workspace = services.settings.workspaces_dir / workflow_id / "repo"
 
-    async def plan(self, job: Job) -> None:
-        repository = await self.deps.gitea.repository(job.repo_owner, job.repo_name)
-        workflow_id = str(uuid4())
-        workspace = self.deps.settings.workspaces_dir / workflow_id / "repo"
-        await self.deps.storage.update_job(job.id, stage="cloning")
-        base_sha = await self.deps.git.clone(
-            job.repo_owner,
-            job.repo_name,
-            repository.default_branch,
-            workspace,
-        )
-        workflow = Workflow(
-            id=workflow_id,
-            kind=WorkflowKind.PLAN,
-            repo_owner=job.repo_owner,
-            repo_name=job.repo_name,
-            issue_number=job.issue_number,
-            workspace_path=workspace,
-            base_sha=base_sha,
-        )
-        await self.deps.storage.create_workflow(workflow)
-        job.workflow_id = workflow.id
-        await self.deps.storage.update_job(job.id, workflow_id=workflow.id, stage="planning")
-        context = await self.deps.context.issue_context(
-            job.repo_owner, job.repo_name, job.issue_number
-        )
-        prompt = self.deps.prompts.render(
-            "plan_initial",
-            context=context,
-            request=job.message or "(no additional request)",
-        )
-        session_id = await self.deps.opencode.create_session(workspace, "plan")
-        workflow.primary_session_id = session_id
-        await self.deps.storage.update_workflow(workflow)
-        await self.deps.storage.update_job(job.id, runtime_session_id=session_id)
-        artifact = await self.deps.opencode.resume(
-            session_id=session_id,
-            workspace=workspace,
-            prompt=prompt,
-            model=self.deps.settings.plan_model,
-            variant=self.deps.settings.plan_variant,
-            schema_name="plan.json",
-            result_type=PlanArtifact,
-        )
-        workflow.artifact = artifact.plan_markdown
-        await self.deps.storage.update_workflow(workflow)
-        report = await self._review_loop(job, workflow, context, artifact)
-        await self._finish(job, workflow, artifact, report)
+    await run.stage("cloning")
+    base_sha = await services.git.clone(
+        job.repo_owner,
+        job.repo_name,
+        default_branch,
+        workspace,
+    )
+    workflow = Workflow(
+        id=workflow_id,
+        kind=WorkflowKind.PLAN,
+        repo_owner=job.repo_owner,
+        repo_name=job.repo_name,
+        issue_number=job.issue_number,
+        workspace_path=workspace,
+        base_sha=base_sha,
+    )
+    await run.create_workflow(workflow, "planning")
 
-    async def discuss(self, job: Job) -> None:
-        workflow = await self._latest_plan(job)
-        if workflow.runtime != "opencode":
+    context = await build_issue_context(
+        services.gitea,
+        services.repository,
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+    )
+    prompt = services.prompts.render(
+        "plan_initial",
+        context=context,
+        request=job.message or "(no additional request)",
+    )
+    session_id = await services.opencode.create_session(workspace, "plan")
+    workflow = replace(workflow, primary_session_id=session_id)
+    await services.repository.save_workflow(workflow)
+    await run.link_session(session_id)
+
+    artifact = await services.opencode.resume(
+        session_id=session_id,
+        workspace=workspace,
+        prompt=prompt,
+        model=services.settings.plan_model,
+        variant=services.settings.plan_variant,
+        schema_name="plan.json",
+        result_type=PlanArtifact,
+    )
+    workflow = replace(workflow, artifact=artifact.plan_markdown)
+    await services.repository.save_workflow(workflow)
+
+    workflow, artifact, report = await review_plan_loop(
+        workflow, context, artifact, run, services
+    )
+    workflow = replace(
+        workflow,
+        artifact=artifact.plan_markdown,
+        review_json=report.model_dump_json(),
+        status=WorkflowStatus.COMPLETED,
+    )
+    await services.repository.save_workflow(workflow)
+    return final_comment("plan", workflow.id, artifact.plan_markdown, report)
+
+
+async def discuss_plan(job: Job, run: JobRun, services: WorkflowServices) -> str:
+    workflow = await _latest_plan(job, services)
+    if workflow.runtime != "opencode":
+        raise JobRejected(
+            "The latest plan predates OpenCode and cannot be resumed; "
+            "start a new `/agent plan`."
+        )
+    if not workflow.primary_session_id or not workflow.artifact:
+        raise JobRejected("The latest plan cannot be resumed; start a new `/agent plan`.")
+
+    await run.link_workflow(workflow.id, "discussing")
+    prompt = services.prompts.render(
+        "discuss", artifact=workflow.artifact, message=job.message or ""
+    )
+    reply = await services.opencode.resume(
+        session_id=workflow.primary_session_id,
+        prompt=prompt,
+        model=services.settings.plan_model,
+        variant=services.settings.plan_variant,
+        workspace=workflow.workspace_path,
+        schema_name="discussion.json",
+        result_type=DiscussionReply,
+    )
+    return agent_comment("discussion", workflow.id, reply.markdown)
+
+
+async def iterate_plan(job: Job, run: JobRun, services: WorkflowServices) -> str:
+    await _reject_if_active_or_merged_pr(job, services)
+    workflow = await _latest_plan(job, services)
+    if workflow.runtime != "opencode":
+        raise JobRejected("The latest plan predates OpenCode; start a new plan.")
+    if not workflow.primary_session_id or not workflow.reviewer_session_id:
+        raise JobRejected("The latest plan is missing resumable sessions; start a new plan.")
+    if not workflow.artifact:
+        raise JobRejected("The latest plan has no saved artifact.")
+
+    await run.link_workflow(workflow.id, "iterating plan")
+    context = await build_issue_context(
+        services.gitea,
+        services.repository,
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+    )
+    prompt = services.prompts.render(
+        "plan_iterate",
+        context=context,
+        artifact=workflow.artifact,
+        review=report_for_prompt(workflow.review_json),
+        message=job.message or "(refine using the latest discussion and prior review)",
+    )
+    artifact = await services.opencode.resume(
+        session_id=workflow.primary_session_id,
+        prompt=prompt,
+        model=services.settings.plan_model,
+        variant=services.settings.plan_variant,
+        workspace=workflow.workspace_path,
+        schema_name="plan.json",
+        result_type=PlanArtifact,
+    )
+    workflow, report = await review_plan_once(workflow, context, artifact, services)
+    workflow = replace(
+        workflow,
+        artifact=artifact.plan_markdown,
+        review_json=report.model_dump_json(),
+        status=WorkflowStatus.COMPLETED,
+    )
+    await services.repository.save_workflow(workflow)
+    return final_comment("plan", workflow.id, artifact.plan_markdown, report)
+
+
+async def _latest_plan(job: Job, services: WorkflowServices) -> Workflow:
+    workflow = await services.repository.latest_workflow(
+        job.repo_owner,
+        job.repo_name,
+        job.issue_number,
+        WorkflowKind.PLAN,
+    )
+    if workflow is None:
+        raise JobRejected("No completed plan exists. Start with `/agent plan`.")
+    return workflow
+
+
+async def _reject_if_active_or_merged_pr(
+    job: Job, services: WorkflowServices
+) -> None:
+    workflows = await services.repository.implementation_workflows(
+        job.repo_owner, job.repo_name, job.issue_number
+    )
+    for workflow in workflows:
+        if workflow.pr_number is None:
+            continue
+        pull = await services.gitea.pull_request(
+            job.repo_owner, job.repo_name, workflow.pr_number
+        )
+        if pull.is_open or pull.merged:
             raise JobRejected(
-                "The latest plan predates OpenCode and cannot be resumed; "
-                "start a new `/agent plan`."
+                f"Issue plan iteration is disabled because agent PR #{pull.number} "
+                "is open or merged. Iterate an open implementation on its PR."
             )
-        if not workflow.primary_session_id or not workflow.artifact:
-            raise JobRejected("The latest plan cannot be resumed; start a new `/agent plan`.")
-        await self.deps.storage.update_job(job.id, workflow_id=workflow.id, stage="discussing")
-        prompt = self.deps.prompts.render(
-            "discuss", artifact=workflow.artifact, message=job.message
-        )
-        reply = await self.deps.opencode.resume(
-            session_id=workflow.primary_session_id,
-            prompt=prompt,
-            model=self.deps.settings.plan_model,
-            variant=self.deps.settings.plan_variant,
-            workspace=workflow.workspace_path,
-            schema_name="discussion.json",
-            result_type=DiscussionReply,
-        )
-        await update_job_comment(
-            self.deps, job, agent_comment("discussion", workflow.id, reply.markdown)
-        )
-
-    async def iterate(self, job: Job) -> None:
-        await self._reject_if_active_or_merged_pr(job)
-        workflow = await self._latest_plan(job)
-        if workflow.runtime != "opencode":
-            raise JobRejected("The latest plan predates OpenCode; start a new plan.")
-        if not workflow.primary_session_id or not workflow.reviewer_session_id:
-            raise JobRejected("The latest plan is missing resumable sessions; start a new plan.")
-        if not workflow.artifact:
-            raise JobRejected("The latest plan has no saved artifact.")
-        await self.deps.storage.update_job(
-            job.id, workflow_id=workflow.id, stage="iterating plan"
-        )
-        context = await self.deps.context.issue_context(
-            job.repo_owner, job.repo_name, job.issue_number
-        )
-        prompt = self.deps.prompts.render(
-            "plan_iterate",
-            context=context,
-            artifact=workflow.artifact,
-            review=report_for_prompt(workflow.review_json),
-            message=job.message or "(refine using the latest discussion and prior review)",
-        )
-        artifact = await self.deps.opencode.resume(
-            session_id=workflow.primary_session_id,
-            prompt=prompt,
-            model=self.deps.settings.plan_model,
-            variant=self.deps.settings.plan_variant,
-            workspace=workflow.workspace_path,
-            schema_name="plan.json",
-            result_type=PlanArtifact,
-        )
-        report = await self._review(workflow, context, artifact)
-        await self._finish(job, workflow, artifact, report)
-
-    async def _review_loop(
-        self, job: Job, workflow: Workflow, context: str, artifact: PlanArtifact
-    ) -> ReviewReport:
-        report = ReviewReport(summary="", findings=[])
-        for round_index in range(self.deps.settings.plan_review_rounds):
-            await self.deps.storage.update_job(
-                job.id,
-                stage=f"reviewing plan {round_index + 1}/"
-                f"{self.deps.settings.plan_review_rounds}",
-            )
-            report = await self._review(workflow, context, artifact)
-            workflow.artifact = artifact.plan_markdown
-            workflow.review_json = report_json(report)
-            await self.deps.storage.update_workflow(workflow)
-            if not report.has_serious_findings:
-                break
-            if round_index == self.deps.settings.plan_review_rounds - 1:
-                break
-            prompt = self.deps.prompts.render(
-                "plan_revision",
-                artifact=artifact.plan_markdown,
-                review=report_for_prompt(workflow.review_json),
-            )
-            artifact = await self.deps.opencode.resume(
-                session_id=required_session(workflow.primary_session_id),
-                prompt=prompt,
-                model=self.deps.settings.plan_model,
-                variant=self.deps.settings.plan_variant,
-                workspace=workflow.workspace_path,
-                schema_name="plan.json",
-                result_type=PlanArtifact,
-            )
-        return report
-
-    async def _review(
-        self, workflow: Workflow, context: str, artifact: PlanArtifact
-    ) -> ReviewReport:
-        prompt = self.deps.prompts.render(
-            "plan_review", context=context, artifact=artifact.plan_markdown
-        )
-        if workflow.reviewer_session_id:
-            return await self.deps.opencode.resume(
-                session_id=workflow.reviewer_session_id,
-                prompt=prompt,
-                model=self.deps.settings.plan_model,
-                variant=self.deps.settings.plan_variant,
-                workspace=workflow.workspace_path,
-                schema_name="review.json",
-                result_type=ReviewReport,
-            )
-        session_id = await self.deps.opencode.create_session(workflow.workspace_path, "plan-review")
-        workflow.reviewer_session_id = session_id
-        await self.deps.storage.update_workflow(workflow)
-        report = await self.deps.opencode.resume(
-            session_id=session_id,
-            workspace=workflow.workspace_path,
-            prompt=prompt,
-            model=self.deps.settings.plan_model,
-            variant=self.deps.settings.plan_variant,
-            schema_name="review.json",
-            result_type=ReviewReport,
-        )
-        return report
-
-    async def _finish(
-        self,
-        job: Job,
-        workflow: Workflow,
-        artifact: PlanArtifact,
-        report: ReviewReport,
-    ) -> None:
-        workflow.artifact = artifact.plan_markdown
-        workflow.review_json = report_json(report)
-        workflow.status = WorkflowStatus.COMPLETED
-        await self.deps.storage.update_workflow(workflow)
-        body = agent_comment("plan", workflow.id, artifact.plan_markdown)
-        remaining = review_markdown(report)
-        if remaining:
-            body = f"{body}\n\n{remaining}"
-        await update_job_comment(self.deps, job, body)
-
-    async def _latest_plan(self, job: Job) -> Workflow:
-        workflow = await self.deps.storage.latest_workflow(
-            job.repo_owner, job.repo_name, job.issue_number, WorkflowKind.PLAN
-        )
-        if workflow is None:
-            raise JobRejected("No completed plan exists. Start with `/agent plan`.")
-        return workflow
-
-    async def _reject_if_active_or_merged_pr(self, job: Job) -> None:
-        workflows = await self.deps.storage.implementation_workflows(
-            job.repo_owner, job.repo_name, job.issue_number
-        )
-        for workflow in workflows:
-            if workflow.pr_number is None:
-                continue
-            pull = await self.deps.gitea.pull_request(
-                job.repo_owner, job.repo_name, workflow.pr_number
-            )
-            if pull.is_open or pull.merged:
-                raise JobRejected(
-                    f"Issue plan iteration is disabled because agent PR #{pull.number} "
-                    "is open or merged. Iterate an open implementation on its PR."
-                )

src/agentci/workflows/pull_request.py

@@ -1,152 +1,160 @@
 from __future__ import annotations
 
-from agentci.domain.models import AgentResult, Job, WorkflowKind, WorkflowStatus
-from agentci.workflows.change_set import ChangeSet, result_comment
-from agentci.workflows.code_review import CodeReviewLoop
-from agentci.workflows.common import (
-    Dependencies,
+from dataclasses import replace
+
+from agentci.engine.model import Job, WorkflowKind, WorkflowStatus
+from agentci.engine.run import JobRun
+from agentci.workflows.context import (
+    build_issue_context,
+    build_pull_request_context,
+)
+from agentci.workflows.implementation import commit_and_push
+from agentci.workflows.model import AgentResult
+from agentci.workflows.render import (
     JobRejected,
     agent_comment,
+    final_comment,
     report_for_prompt,
-    report_json,
-    review_markdown,
-    update_job_comment,
+    result_comment,
 )
+from agentci.workflows.review import review_implementation_once
+from agentci.workflows.services import WorkflowServices
 
 
-class PullRequestWorkflow:
-    def __init__(self, dependencies: Dependencies) -> None:
-        self.deps = dependencies
-        self.review = CodeReviewLoop(dependencies)
-        self.changes = ChangeSet(dependencies)
+async def iterate_implementation(
+    job: Job, run: JobRun, services: WorkflowServices
+) -> str:
+    pull_number = _pull_number(job)
+    workflow = await services.repository.workflow_for_pr(
+        job.repo_owner, job.repo_name, pull_number
+    )
+    if workflow is None or workflow.status is not WorkflowStatus.COMPLETED:
+        raise JobRejected(
+            "This is not an open agent-created implementation PR. Use `/agent fix`."
+        )
+    if workflow.runtime != "opencode":
+        raise JobRejected("The implementation predates OpenCode and cannot be resumed.")
+    if not workflow.primary_session_id or not workflow.reviewer_session_id:
+        raise JobRejected("The implementation sessions cannot be resumed.")
 
-    async def iterate(self, job: Job) -> None:
-        pull_number = _pull_number(job)
-        workflow = await self.deps.storage.workflow_for_pr(
-            job.repo_owner, job.repo_name, pull_number
-        )
-        if workflow is None or workflow.status is not WorkflowStatus.COMPLETED:
-            raise JobRejected(
-                "This is not an open agent-created implementation PR. Use `/agent fix`."
-            )
-        if workflow.runtime != "opencode":
-            raise JobRejected("The implementation predates OpenCode and cannot be resumed.")
-        if not workflow.primary_session_id or not workflow.reviewer_session_id:
-            raise JobRejected("The implementation sessions cannot be resumed.")
-        pull, context = await self.deps.context.pull_request_context(
-            job.repo_owner, job.repo_name, pull_number
-        )
-        if not pull.is_open:
-            raise JobRejected("Implementation iteration requires an open pull request.")
-        if workflow.branch != pull.head_branch:
-            raise JobRejected("The pull request head branch no longer matches its workflow.")
-        await self.deps.storage.update_job(
-            job.id, workflow_id=workflow.id, stage="synchronizing branch"
-        )
-        job.workflow_id = workflow.id
-        await self.deps.git.sync_branch(workflow.workspace_path, pull.head_branch)
-        await self.deps.storage.update_job(
-            job.id, stage="installing development environment"
-        )
-        await self.deps.development.prepare(workflow.workspace_path)
-        await self.deps.storage.update_job(job.id, stage="implementing iteration")
-        prompt = self.deps.prompts.render(
-            "implementation_iterate",
-            context=context,
-            review=report_for_prompt(workflow.review_json),
-            message=job.message or "(perform one additional reviewed refinement)",
-            development_environment=self.deps.development.description,
-        )
-        result = await self.deps.opencode.resume(
-            session_id=workflow.primary_session_id,
-            prompt=prompt,
-            model=self.deps.settings.implement_model,
-            variant=self.deps.settings.implement_variant,
-            workspace=workflow.workspace_path,
-            schema_name="agent_result.json",
-            result_type=AgentResult,
-        )
-        issue_context = await self.deps.context.issue_context(
-            job.repo_owner, job.repo_name, workflow.issue_number
-        )
-        plan = await self.deps.storage.latest_workflow(
-            job.repo_owner, job.repo_name, workflow.issue_number, WorkflowKind.PLAN
-        )
-        report = await self.review.once(
-            workflow,
-            issue_context=issue_context,
-            plan=plan.artifact if plan and plan.artifact else "(no canonical plan)",
-            pull_context=context,
-        )
-        sha = await self.changes.commit_and_push(
-            job,
-            workflow.workspace_path,
-            pull.head_branch,
-            result,
-            set_upstream=False,
-            commit_prefix="agent iterate",
-        )
-        workflow.artifact = result.model_dump_json()
-        workflow.review_json = report_json(report)
-        await self.deps.storage.update_workflow(workflow)
-        body = agent_comment(
-            "iteration", workflow.id, result_comment(result, sha=sha)
-        )
-        remaining = review_markdown(report)
-        if remaining:
-            body = f"{body}\n\n{remaining}"
-        await update_job_comment(self.deps, job, body)
+    pull, context = await build_pull_request_context(
+        services.gitea, job.repo_owner, job.repo_name, pull_number
+    )
+    if not pull.is_open:
+        raise JobRejected("Implementation iteration requires an open pull request.")
+    if workflow.branch != pull.head_branch:
+        raise JobRejected("The pull request head branch no longer matches its workflow.")
 
-    async def fix(self, job: Job) -> None:
-        pull_number = _pull_number(job)
-        pull, context = await self.deps.context.pull_request_context(
-            job.repo_owner, job.repo_name, pull_number
-        )
-        if not pull.is_open:
-            raise JobRejected("Fixes require an open pull request.")
-        workspace = self.deps.settings.workspaces_dir / f"fix-{job.id}" / "repo"
-        await self.deps.storage.update_job(job.id, stage="cloning pull request")
-        await self.deps.git.clone(
-            pull.head_owner,
-            pull.head_repo,
-            pull.head_branch,
-            workspace,
-        )
-        await self.deps.storage.update_job(
-            job.id, stage="installing development environment"
-        )
-        await self.deps.development.prepare(workspace)
-        prompt = self.deps.prompts.render(
-            "fix",
-            context=context,
-            message=job.message or "(address the pull request feedback)",
-            development_environment=self.deps.development.description,
-        )
-        await self.deps.storage.update_job(job.id, stage="fixing")
-        session_id = await self.deps.opencode.create_session(workspace, "fix")
-        await self.deps.storage.update_job(job.id, runtime_session_id=session_id)
-        result = await self.deps.opencode.resume(
-            session_id=session_id,
-            workspace=workspace,
-            prompt=prompt,
-            model=self.deps.settings.implement_model,
-            variant=self.deps.settings.implement_variant,
-            schema_name="agent_result.json",
-            result_type=AgentResult,
-        )
-        sha = await self.changes.commit_and_push(
-            job,
-            workspace,
-            pull.head_branch,
-            result,
-            set_upstream=False,
-            commit_prefix="agent fix",
-        )
-        await update_job_comment(
-            self.deps,
-            job,
-            agent_comment("fix", job.id, result_comment(result, sha=sha)),
-        )
+    await run.link_workflow(workflow.id, "synchronizing branch")
+    await services.git.sync_branch(workflow.workspace_path, pull.head_branch)
+    await run.stage("installing development environment")
+    await services.development.prepare(workflow.workspace_path)
+    await run.stage("implementing iteration")
+    prompt = services.prompts.render(
+        "implementation_iterate",
+        context=context,
+        review=report_for_prompt(workflow.review_json),
+        message=job.message or "(perform one additional reviewed refinement)",
+        development_environment=services.development.description,
+    )
+    result = await services.opencode.resume(
+        session_id=workflow.primary_session_id,
+        prompt=prompt,
+        model=services.settings.implement_model,
+        variant=services.settings.implement_variant,
+        workspace=workflow.workspace_path,
+        schema_name="agent_result.json",
+        result_type=AgentResult,
+    )
+
+    issue_context = await build_issue_context(
+        services.gitea,
+        services.repository,
+        job.repo_owner,
+        job.repo_name,
+        workflow.issue_number,
+    )
+    plan = await services.repository.latest_workflow(
+        job.repo_owner,
+        job.repo_name,
+        workflow.issue_number,
+        WorkflowKind.PLAN,
+    )
+    workflow, report = await review_implementation_once(
+        workflow,
+        issue_context=issue_context,
+        plan=plan.artifact if plan and plan.artifact else "(no canonical plan)",
+        pull_context=context,
+        services=services,
+    )
+    sha = await commit_and_push(
+        run,
+        services,
+        workflow.workspace_path,
+        pull.head_branch,
+        result,
+        set_upstream=False,
+        commit_prefix="agent iterate",
+    )
+    workflow = replace(
+        workflow,
+        artifact=result.model_dump_json(),
+        review_json=report.model_dump_json(),
+    )
+    await services.repository.save_workflow(workflow)
+    return final_comment(
+        "iteration", workflow.id, result_comment(result, sha=sha), report
+    )
+
+
+async def fix_pull_request(
+    job: Job, run: JobRun, services: WorkflowServices
+) -> str:
+    pull_number = _pull_number(job)
+    pull, context = await build_pull_request_context(
+        services.gitea, job.repo_owner, job.repo_name, pull_number
+    )
+    if not pull.is_open:
+        raise JobRejected("Fixes require an open pull request.")
+
+    workspace = services.settings.workspaces_dir / f"fix-{job.id}" / "repo"
+    await run.stage("cloning pull request")
+    await services.git.clone(
+        pull.head_owner,
+        pull.head_repo,
+        pull.head_branch,
+        workspace,
+    )
+    await run.stage("installing development environment")
+    await services.development.prepare(workspace)
+    prompt = services.prompts.render(
+        "fix",
+        context=context,
+        message=job.message or "(address the pull request feedback)",
+        development_environment=services.development.description,
+    )
+    await run.stage("fixing")
+    session_id = await services.opencode.create_session(workspace, "fix")
+    await run.link_session(session_id)
+    result = await services.opencode.resume(
+        session_id=session_id,
+        workspace=workspace,
+        prompt=prompt,
+        model=services.settings.implement_model,
+        variant=services.settings.implement_variant,
+        schema_name="agent_result.json",
+        result_type=AgentResult,
+    )
+    sha = await commit_and_push(
+        run,
+        services,
+        workspace,
+        pull.head_branch,
+        result,
+        set_upstream=False,
+        commit_prefix="agent fix",
+    )
+    return agent_comment("fix", job.id, result_comment(result, sha=sha))
 
 
 def _pull_number(job: Job) -> int:

src/agentci/workflows/render.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+
+from agentci.workflows.model import AgentResult, ReviewReport
+
+
+class JobRejected(RuntimeError):
+    """A safe, expected workflow rejection to publish to the requester."""
+
+
+def required_session(value: str | None) -> str:
+    if value is None:
+        raise RuntimeError("Expected a persisted OpenCode session ID")
+    return value
+
+
+def review_markdown(report: ReviewReport) -> str:
+    if not report.findings:
+        return ""
+    lines = ["## Remaining review findings", "", report.summary]
+    for finding in report.findings:
+        location = f" \u2014 `{finding.location}`" if finding.location else ""
+        lines.extend(
+            [
+                "",
+                f"### {finding.severity.value.upper()}: {finding.title}{location}",
+                finding.detail,
+                "",
+                f"Recommendation: {finding.recommendation}",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def report_for_prompt(stored_review: str | None) -> str:
+    if not stored_review:
+        return "(none)"
+    try:
+        return json.dumps(json.loads(stored_review), indent=2)
+    except json.JSONDecodeError:
+        return stored_review
+
+
+def agent_comment(kind: str, workflow_id: str, body: str) -> str:
+    return f"<!-- agentci:{kind} workflow={workflow_id} -->\n{body}"
+
+
+def final_comment(
+    kind: str,
+    workflow_id: str,
+    body: str,
+    report: ReviewReport | None = None,
+) -> str:
+    rendered = agent_comment(kind, workflow_id, body)
+    remaining = review_markdown(report) if report else ""
+    return f"{rendered}\n\n{remaining}" if remaining else rendered
+
+
+def pull_request_body(issue_number: int, result: AgentResult) -> str:
+    tests = "\n".join(f"- {item}" for item in result.tests) or "- Not reported"
+    return (
+        f"Closes #{issue_number}\n\n"
+        f"## Implementation\n\n{result.summary_markdown}\n\n"
+        f"## Validation\n\n{tests}\n\n"
+        "_Created by Agent CI._"
+    )
+
+
+def result_comment(result: AgentResult, *, sha: str | None = None) -> str:
+    tests = "\n".join(f"- {item}" for item in result.tests) or "- Not reported"
+    commit = f"\n\nCommit: `{sha}`" if sha else ""
+    return f"## Agent result\n\n{result.summary_markdown}\n\n## Validation\n\n{tests}{commit}"
+
+
+def commit_title(markdown: str) -> str:
+    for line in markdown.splitlines():
+        value = line.strip().lstrip("#").strip()
+        if value:
+            return value[:72]
+    return "apply requested changes"

src/agentci/workflows/review.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from agentci.engine.model import Workflow
+from agentci.engine.run import JobRun
+from agentci.workflows.model import AgentResult, PlanArtifact, ReviewReport
+from agentci.workflows.render import report_for_prompt, required_session
+from agentci.workflows.services import WorkflowServices
+
+
+async def review_plan_loop(
+    workflow: Workflow,
+    context: str,
+    artifact: PlanArtifact,
+    run: JobRun,
+    services: WorkflowServices,
+) -> tuple[Workflow, PlanArtifact, ReviewReport]:
+    report = ReviewReport(summary="", findings=[])
+    for round_index in range(services.settings.plan_review_rounds):
+        await run.stage(
+            f"reviewing plan {round_index + 1}/{services.settings.plan_review_rounds}"
+        )
+        workflow, report = await review_plan_once(
+            workflow, context, artifact, services
+        )
+        workflow = replace(
+            workflow,
+            artifact=artifact.plan_markdown,
+            review_json=report.model_dump_json(),
+        )
+        await services.repository.save_workflow(workflow)
+        if not report.has_serious_findings:
+            break
+        if round_index == services.settings.plan_review_rounds - 1:
+            break
+        prompt = services.prompts.render(
+            "plan_revision",
+            artifact=artifact.plan_markdown,
+            review=report_for_prompt(workflow.review_json),
+        )
+        artifact = await services.opencode.resume(
+            session_id=required_session(workflow.primary_session_id),
+            prompt=prompt,
+            model=services.settings.plan_model,
+            variant=services.settings.plan_variant,
+            workspace=workflow.workspace_path,
+            schema_name="plan.json",
+            result_type=PlanArtifact,
+        )
+        workflow = replace(workflow, artifact=artifact.plan_markdown)
+        await services.repository.save_workflow(workflow)
+    return workflow, artifact, report
+
+
+async def review_plan_once(
+    workflow: Workflow,
+    context: str,
+    artifact: PlanArtifact,
+    services: WorkflowServices,
+) -> tuple[Workflow, ReviewReport]:
+    prompt = services.prompts.render(
+        "plan_review", context=context, artifact=artifact.plan_markdown
+    )
+    if workflow.reviewer_session_id:
+        report = await services.opencode.resume(
+            session_id=workflow.reviewer_session_id,
+            prompt=prompt,
+            model=services.settings.plan_model,
+            variant=services.settings.plan_variant,
+            workspace=workflow.workspace_path,
+            schema_name="review.json",
+            result_type=ReviewReport,
+        )
+        return workflow, report
+
+    session_id = await services.opencode.create_session(
+        workflow.workspace_path, "plan-review"
+    )
+    workflow = replace(workflow, reviewer_session_id=session_id)
+    await services.repository.save_workflow(workflow)
+    report = await services.opencode.resume(
+        session_id=session_id,
+        workspace=workflow.workspace_path,
+        prompt=prompt,
+        model=services.settings.plan_model,
+        variant=services.settings.plan_variant,
+        schema_name="review.json",
+        result_type=ReviewReport,
+    )
+    return workflow, report
+
+
+async def review_implementation_loop(
+    workflow: Workflow,
+    issue_context: str,
+    plan: str,
+    result: AgentResult,
+    run: JobRun,
+    services: WorkflowServices,
+) -> tuple[Workflow, AgentResult, ReviewReport]:
+    report = ReviewReport(summary="", findings=[])
+    for round_index in range(services.settings.implement_review_rounds):
+        await run.stage(
+            f"reviewing implementation {round_index + 1}/"
+            f"{services.settings.implement_review_rounds}"
+        )
+        workflow, report = await review_implementation_once(
+            workflow,
+            issue_context=issue_context,
+            plan=plan,
+            pull_context=(
+                "The proposed pull request is the current uncommitted working-tree diff. "
+                "Review only that diff."
+            ),
+            services=services,
+        )
+        workflow = replace(
+            workflow,
+            artifact=result.model_dump_json(),
+            review_json=report.model_dump_json(),
+        )
+        await services.repository.save_workflow(workflow)
+        if not report.has_serious_findings:
+            break
+        if round_index == services.settings.implement_review_rounds - 1:
+            break
+        prompt = services.prompts.render(
+            "implementation_revision",
+            review=report_for_prompt(workflow.review_json),
+            development_environment=services.development.description,
+        )
+        result = await services.opencode.resume(
+            session_id=required_session(workflow.primary_session_id),
+            prompt=prompt,
+            model=services.settings.implement_model,
+            variant=services.settings.implement_variant,
+            workspace=workflow.workspace_path,
+            schema_name="agent_result.json",
+            result_type=AgentResult,
+        )
+        workflow = replace(workflow, artifact=result.model_dump_json())
+        await services.repository.save_workflow(workflow)
+    return workflow, result, report
+
+
+async def review_implementation_once(
+    workflow: Workflow,
+    *,
+    issue_context: str,
+    plan: str,
+    pull_context: str,
+    services: WorkflowServices,
+) -> tuple[Workflow, ReviewReport]:
+    prompt = services.prompts.render(
+        "implementation_review",
+        issue_context=issue_context,
+        artifact=plan,
+        pull_context=pull_context,
+    )
+    if workflow.reviewer_session_id:
+        report = await services.opencode.resume(
+            session_id=workflow.reviewer_session_id,
+            prompt=prompt,
+            model=services.settings.implement_model,
+            variant=services.settings.implement_variant,
+            workspace=workflow.workspace_path,
+            schema_name="review.json",
+            result_type=ReviewReport,
+        )
+        return workflow, report
+
+    session_id = await services.opencode.create_session(
+        workflow.workspace_path, "implementation-review"
+    )
+    workflow = replace(workflow, reviewer_session_id=session_id)
+    await services.repository.save_workflow(workflow)
+    report = await services.opencode.resume(
+        session_id=session_id,
+        workspace=workflow.workspace_path,
+        prompt=prompt,
+        model=services.settings.implement_model,
+        variant=services.settings.implement_variant,
+        schema_name="review.json",
+        result_type=ReviewReport,
+    )
+    return workflow, report

src/agentci/workflows/services.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentci.config.settings import Settings
+from agentci.engine.repository import Repository
+from agentci.integrations.development import DevelopmentEnvironment
+from agentci.integrations.git import Git
+from agentci.integrations.gitea.client import Gitea
+from agentci.integrations.opencode.client import OpenCode
+from agentci.prompts.library import PromptLibrary
+
+
+@dataclass(frozen=True)
+class WorkflowServices:
+    settings: Settings
+    repository: Repository
+    gitea: Gitea
+    git: Git
+    opencode: OpenCode
+    prompts: PromptLibrary
+    development: DevelopmentEnvironment

tests/conftest.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+from agentci.engine import _sqlite
+from agentci.engine.repository import Repository
+
+
+@pytest.fixture
+async def engine_repository(tmp_path: Path) -> Repository:
+    repository = Repository(tmp_path / "state.sqlite3")
+    await repository.initialize()
+    return repository
+
+
+@dataclass
+class SQLiteClock:
+    now: str = "2026-02-01T00:00:00+00:00"
+
+
+@pytest.fixture
+def sqlite_clock(monkeypatch: pytest.MonkeyPatch) -> SQLiteClock:
+    clock = SQLiteClock()
+    monkeypatch.setattr(_sqlite, "now", lambda: clock.now)
+    return clock

tests/test_app.py

@@ -0,0 +1,130 @@
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+import agentci.api.app as app_module
+import agentci.api.lifespan as lifespan_module
+
+
+class BlockingWorker:
+    def __init__(self, events: list[str]) -> None:
+        self.events = events
+        self.started = asyncio.Event()
+
+    async def run(self, stop: asyncio.Event) -> None:
+        self.events.append("worker-started")
+        self.started.set()
+        try:
+            await stop.wait()
+        except asyncio.CancelledError:
+            self.events.append(f"worker-cancelled:{stop.is_set()}")
+            raise
+
+
+class FailingWorker:
+    def __init__(self) -> None:
+        self.started = asyncio.Event()
+
+    async def run(self, _stop: asyncio.Event) -> None:
+        self.started.set()
+        raise RuntimeError("worker failed")
+
+
+class FakeRuntime:
+    def __init__(self, worker: object, events: list[str]) -> None:
+        self.worker = worker
+        self.events = events
+        self.closed = False
+
+    async def close(self) -> None:
+        self.events.append("runtime-closed")
+        self.closed = True
+
+
+async def test_lifespan_starts_worker_cancels_it_and_closes_runtime(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    events: list[str] = []
+    worker = BlockingWorker(events)
+    runtime = FakeRuntime(worker, events)
+    selected_settings = SimpleNamespace(name="selected")
+    built_with: list[object] = []
+    configured: list[bool] = []
+
+    async def build(settings: object) -> FakeRuntime:
+        built_with.append(settings)
+        return runtime
+
+    monkeypatch.setattr(lifespan_module, "build_runtime", build)
+    monkeypatch.setattr(lifespan_module, "configure_logging", lambda: configured.append(True))
+    application = app_module.create_app(selected_settings)  # type: ignore[arg-type]
+
+    async with application.router.lifespan_context(application):
+        await worker.started.wait()
+        assert application.state.runtime is runtime
+        assert not runtime.closed
+
+    assert built_with == [selected_settings]
+    assert configured == [True]
+    assert events == ["worker-started", "worker-cancelled:True", "runtime-closed"]
+
+
+async def test_lifespan_closes_runtime_when_worker_task_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    events: list[str] = []
+    worker = FailingWorker()
+    runtime = FakeRuntime(worker, events)
+
+    async def build(_settings: object) -> FakeRuntime:
+        return runtime
+
+    monkeypatch.setattr(lifespan_module, "build_runtime", build)
+    monkeypatch.setattr(lifespan_module, "configure_logging", lambda: None)
+    application = app_module.create_app(SimpleNamespace())  # type: ignore[arg-type]
+
+    with pytest.raises(RuntimeError, match="worker failed"):
+        async with application.router.lifespan_context(application):
+            await worker.started.wait()
+
+    assert runtime.closed
+    assert events == ["runtime-closed"]
+
+
+async def test_lifespan_propagates_runtime_startup_failure_without_starting_worker(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    configured: list[bool] = []
+
+    async def fail_build(_settings: object) -> None:
+        raise RuntimeError("database unavailable")
+
+    monkeypatch.setattr(lifespan_module, "build_runtime", fail_build)
+    monkeypatch.setattr(lifespan_module, "configure_logging", lambda: configured.append(True))
+    application = app_module.create_app(SimpleNamespace())  # type: ignore[arg-type]
+
+    with pytest.raises(RuntimeError, match="database unavailable"):
+        async with application.router.lifespan_context(application):
+            pytest.fail("startup failure must prevent serving requests")
+
+    assert configured == [True]
+    assert not hasattr(application.state, "runtime")
+
+
+async def test_global_exception_handler_returns_safe_json() -> None:
+    application = app_module.create_app(SimpleNamespace())  # type: ignore[arg-type]
+
+    @application.get("/explode")
+    async def explode() -> None:
+        raise RuntimeError("sensitive provider detail")
+
+    async with AsyncClient(
+        transport=ASGITransport(app=application, raise_app_exceptions=False),
+        base_url="http://test",
+    ) as client:
+        response = await client.get("/explode")
+
+    assert response.status_code == 500
+    assert response.json() == {"detail": "Internal server error. See service logs for diagnostics."}

tests/test_code_review.py

@@ -1,25 +1,31 @@
+from collections.abc import Iterable
 from pathlib import Path
 from types import SimpleNamespace
 
-from agentci.domain.models import (
+from pydantic import BaseModel
+
+from agentci.engine.model import Workflow, WorkflowKind
+from agentci.workflows.model import (
     AgentResult,
-    Job,
-    JobKind,
+    PlanArtifact,
     ReviewFinding,
     ReviewReport,
     ReviewSeverity,
-    Workflow,
-    WorkflowKind,
 )
-from agentci.workflows.code_review import CodeReviewLoop
+from agentci.workflows.review import review_implementation_loop, review_plan_loop
+from tests.workflow_support import WorkflowHarness, make_workflow_harness
 
 
-def serious_report() -> ReviewReport:
+def serious_report(
+    summary: str = "Needs work",
+    *,
+    severity: ReviewSeverity = ReviewSeverity.MAJOR,
+) -> ReviewReport:
     return ReviewReport(
-        summary="Needs work",
+        summary=summary,
         findings=[
             ReviewFinding(
-                severity=ReviewSeverity.MAJOR,
+                severity=severity,
                 title="Missing check",
                 detail="A check is absent.",
                 recommendation="Add it.",
@@ -28,101 +34,289 @@ def serious_report() -> ReviewReport:
     )
 
 
-class FakeOpenCode:
-    def __init__(self, reports: list[ReviewReport]) -> None:
-        self.reports = iter(reports)
-        self.reviews = 0
-        self.revisions = 0
-
-    async def create_session(self, *_args):
-        return "reviewer"
-
-    async def resume(self, **kwargs):
-        if kwargs["result_type"] is ReviewReport:
-            self.reviews += 1
-            return next(self.reports)
-        self.revisions += 1
-        return AgentResult(summary_markdown=f"revision {self.revisions}", tests=[])
+def clean_report() -> ReviewReport:
+    return ReviewReport(summary="Ready", findings=[])
 
 
-class FakeStorage:
-    async def update_job(self, *_args, **_kwargs):
-        return None
-
-    async def update_workflow(self, *_args, **_kwargs):
-        return None
-
-
-class FakePrompts:
-    def render(self, name, **_kwargs):
-        return name
-
-
-def objects(rounds: int, reports: list[ReviewReport]):
-    opencode = FakeOpenCode(reports)
-    settings = SimpleNamespace(
-        implement_review_rounds=rounds,
-        implement_model="model",
-        implement_variant="high",
+def minor_report() -> ReviewReport:
+    return ReviewReport(
+        summary="Optional improvement",
+        findings=[
+            ReviewFinding(
+                severity=ReviewSeverity.MINOR,
+                title="Clarify wording",
+                detail="The wording could be clearer.",
+                recommendation="Tighten it when convenient.",
+            )
+        ],
     )
-    deps = SimpleNamespace(
-        settings=settings,
-        opencode=opencode,
-        storage=FakeStorage(),
-        prompts=FakePrompts(),
-        development=SimpleNamespace(description="python"),
-    )
-    workflow = Workflow(
+
+
+class FakeRepository:
+    def __init__(self, trace: list[tuple[object, ...]] | None = None) -> None:
+        self.saved_workflows: list[Workflow] = []
+        self.trace = trace
+
+    async def save_workflow(self, workflow: Workflow) -> None:
+        self.saved_workflows.append(workflow)
+        if self.trace is not None:
+            self.trace.append(("save_workflow", workflow.reviewer_session_id))
+
+
+def workflow(*, reviewer_session_id: str | None = None) -> Workflow:
+    return Workflow(
         id="flow",
         kind=WorkflowKind.IMPLEMENT,
         repo_owner="org",
         repo_name="repo",
         issue_number=1,
-        workspace_path=Path("."),
+        workspace_path=Path("/workspace/repo"),
         base_sha="abc",
-        primary_session_id="primary",
+        primary_session_id="primary-session",
+        reviewer_session_id=reviewer_session_id,
     )
-    job = Job(
-        id="job",
-        kind=JobKind.IMPLEMENT,
-        target_key="target",
-        repo_owner="org",
-        repo_name="repo",
-        issue_number=1,
-        pr_number=None,
-        requester="alice",
-        message="",
-        comment_id=1,
-    )
-    return CodeReviewLoop(deps), opencode, workflow, job  # type: ignore[arg-type]
 
 
-async def test_stops_after_clean_second_review() -> None:
-    clean = ReviewReport(summary="Ready", findings=[])
-    loop, opencode, workflow, job = objects(4, [serious_report(), clean])
-    _, report = await loop.run(
-        job,
-        workflow,
+def review_harness(
+    responses: Iterable[BaseModel],
+    repository: FakeRepository,
+    *,
+    trace: list[tuple[object, ...]] | None = None,
+    plan_rounds: int = 4,
+    implementation_rounds: int = 3,
+) -> WorkflowHarness:
+    return make_workflow_harness(
+        settings=SimpleNamespace(
+            plan_review_rounds=plan_rounds,
+            plan_model="provider/plan",
+            plan_variant="high",
+            implement_review_rounds=implementation_rounds,
+            implement_model="provider/implement",
+            implement_variant="high",
+        ),
+        repository=repository,
+        gitea=object(),
+        responses=responses,
+        trace=trace,
+    )
+
+
+async def test_implementation_loop_persists_reviewed_revision_and_stops_clean() -> None:
+    revised = AgentResult(summary_markdown="revision 1", tests=["pytest: passed"])
+    repository = FakeRepository()
+    harness = review_harness(
+        [serious_report(), revised, clean_report()],
+        repository,
+        implementation_rounds=4,
+    )
+    original = workflow()
+
+    updated, result, report = await review_implementation_loop(
+        original,
         "issue context",
         "canonical plan",
         AgentResult(summary_markdown="initial", tests=[]),
+        harness.run,
+        harness.services,
     )
+
+    assert result == revised
+    assert report == clean_report()
+    assert original.reviewer_session_id is None
+    assert updated.reviewer_session_id == "implementation-review-session"
+    assert updated.artifact == revised.model_dump_json()
+    assert updated.review_json == clean_report().model_dump_json()
+    assert repository.saved_workflows[-1] == updated
+    assert repository.saved_workflows[0].reviewer_session_id == ("implementation-review-session")
+    assert harness.run.stages == [
+        "reviewing implementation 1/4",
+        "reviewing implementation 2/4",
+    ]
+    assert harness.opencode.created_sessions == [(original.workspace_path, "implementation-review")]
+    assert [call["session_id"] for call in harness.opencode.resume_calls] == [
+        "implementation-review-session",
+        "primary-session",
+        "implementation-review-session",
+    ]
+    assert [call["result_type"] for call in harness.opencode.resume_calls] == [
+        ReviewReport,
+        AgentResult,
+        ReviewReport,
+    ]
+    assert [name for name, _ in harness.prompts.calls] == [
+        "implementation_review",
+        "implementation_revision",
+        "implementation_review",
+    ]
+    assert harness.opencode.responses == []
+
+
+async def test_implementation_loop_never_makes_unreviewed_final_revision() -> None:
+    final_report = serious_report(
+        "Still failing after the last review",
+        severity=ReviewSeverity.BLOCKING,
+    )
+    repository = FakeRepository()
+    harness = review_harness(
+        [
+            serious_report("round 1"),
+            AgentResult(summary_markdown="revision 1", tests=[]),
+            serious_report("round 2"),
+            AgentResult(summary_markdown="revision 2", tests=[]),
+            final_report,
+        ],
+        repository,
+        implementation_rounds=3,
+    )
+
+    updated, result, report = await review_implementation_loop(
+        workflow(),
+        "issue context",
+        "canonical plan",
+        AgentResult(summary_markdown="initial", tests=[]),
+        harness.run,
+        harness.services,
+    )
+
+    assert result.summary_markdown == "revision 2"
+    assert report is final_report
+    assert updated.artifact == result.model_dump_json()
+    assert updated.review_json == final_report.model_dump_json()
+    assert repository.saved_workflows[-1] == updated
+    assert [call["result_type"] for call in harness.opencode.resume_calls] == [
+        ReviewReport,
+        AgentResult,
+        ReviewReport,
+        AgentResult,
+        ReviewReport,
+    ]
+    assert harness.run.stages == [
+        "reviewing implementation 1/3",
+        "reviewing implementation 2/3",
+        "reviewing implementation 3/3",
+    ]
+    assert harness.opencode.responses == []
+
+
+async def test_plan_loop_revises_serious_finding_then_persists_clean_result() -> None:
+    revised = PlanArtifact(plan_markdown="Revised plan")
+    trace: list[tuple[object, ...]] = []
+    repository = FakeRepository(trace)
+    harness = review_harness(
+        [serious_report(), revised, clean_report()],
+        repository,
+        trace=trace,
+        plan_rounds=4,
+    )
+    original = workflow()
+    initial = PlanArtifact(plan_markdown="Initial plan")
+
+    updated, artifact, report = await review_plan_loop(
+        original,
+        "issue context",
+        initial,
+        harness.run,
+        harness.services,
+    )
+
+    assert artifact is revised
+    assert report == clean_report()
+    assert original.reviewer_session_id is None
+    assert updated.reviewer_session_id == "plan-review-session"
+    assert updated.artifact == "Revised plan"
+    assert updated.review_json == clean_report().model_dump_json()
+    assert repository.saved_workflows[-1] == updated
+    assert harness.run.stages == ["reviewing plan 1/4", "reviewing plan 2/4"]
+    assert harness.opencode.created_sessions == [(original.workspace_path, "plan-review")]
+    assert harness.opencode.resume_calls[0] == {
+        "session_id": "plan-review-session",
+        "workspace": original.workspace_path,
+        "prompt": "rendered plan_review",
+        "model": "provider/plan",
+        "variant": "high",
+        "schema_name": "review.json",
+        "result_type": ReviewReport,
+    }
+    assert harness.prompts.calls[0] == (
+        "plan_review",
+        {"context": "issue context", "artifact": "Initial plan"},
+    )
+    assert trace[:3] == [
+        ("create_session", "plan-review", "plan-review-session"),
+        ("save_workflow", "plan-review-session"),
+        ("resume", "plan-review-session", ReviewReport),
+    ]
+    assert [call["session_id"] for call in harness.opencode.resume_calls] == [
+        "plan-review-session",
+        "primary-session",
+        "plan-review-session",
+    ]
+    assert [name for name, _ in harness.prompts.calls] == [
+        "plan_review",
+        "plan_revision",
+        "plan_review",
+    ]
+    assert harness.opencode.responses == []
+
+
+async def test_plan_loop_stops_at_round_boundary_without_unreviewed_revision() -> None:
+    final_report = serious_report("round 2")
+    repository = FakeRepository()
+    harness = review_harness(
+        [
+            serious_report("round 1"),
+            PlanArtifact(plan_markdown="Only revision"),
+            final_report,
+        ],
+        repository,
+        plan_rounds=2,
+    )
+
+    updated, artifact, report = await review_plan_loop(
+        workflow(),
+        "issue context",
+        PlanArtifact(plan_markdown="Initial plan"),
+        harness.run,
+        harness.services,
+    )
+
+    assert artifact.plan_markdown == "Only revision"
+    assert report is final_report
+    assert updated.artifact == "Only revision"
+    assert updated.review_json == final_report.model_dump_json()
+    assert repository.saved_workflows[-1] == updated
+    assert [call["result_type"] for call in harness.opencode.resume_calls] == [
+        ReviewReport,
+        PlanArtifact,
+        ReviewReport,
+    ]
+    assert harness.run.stages == ["reviewing plan 1/2", "reviewing plan 2/2"]
+    assert harness.opencode.responses == []
+
+
+async def test_minor_findings_end_review_loop_without_revision() -> None:
+    repository = FakeRepository()
+    harness = review_harness(
+        [minor_report()],
+        repository,
+        implementation_rounds=5,
+    )
+    initial = AgentResult(summary_markdown="initial", tests=[])
+
+    updated, result, report = await review_implementation_loop(
+        workflow(),
+        "issue context",
+        "canonical plan",
+        initial,
+        harness.run,
+        harness.services,
+    )
+
+    assert result is initial
+    assert report == minor_report()
     assert not report.has_serious_findings
-    assert opencode.reviews == 2
-    assert opencode.revisions == 1
-
-
-async def test_does_not_make_unreviewed_final_revision() -> None:
-    loop, opencode, workflow, job = objects(
-        3, [serious_report(), serious_report(), serious_report()]
-    )
-    _, report = await loop.run(
-        job,
-        workflow,
-        "issue context",
-        "canonical plan",
-        AgentResult(summary_markdown="initial", tests=[]),
-    )
-    assert report.has_serious_findings
-    assert opencode.reviews == 3
-    assert opencode.revisions == 2
+    assert updated.artifact == initial.model_dump_json()
+    assert updated.review_json == minor_report().model_dump_json()
+    assert repository.saved_workflows[-1] == updated
+    assert [call["result_type"] for call in harness.opencode.resume_calls] == [ReviewReport]
+    assert harness.run.stages == ["reviewing implementation 1/5"]

tests/test_codegraph.py

@@ -1,59 +1,151 @@
+import asyncio
+from collections.abc import Sequence
 from pathlib import Path
+from typing import Any
 
-from agentci.adapters.codegraph import CodeGraphClient
+import pytest
+
+from agentci.integrations.codegraph import CodeGraph, CodeGraphError
 
 
 class FakeProcess:
-    returncode = 0
+    def __init__(self, returncode: int = 0, stderr: bytes = b"") -> None:
+        self.returncode = returncode
+        self.stderr = stderr
 
     async def communicate(self) -> tuple[bytes, bytes]:
-        return b"", b""
+        return b"", self.stderr
 
 
-async def test_initializes_incomplete_index_and_excludes_it_from_git(
-    tmp_path: Path, monkeypatch
+class CodeGraphProcessRecorder:
+    def __init__(self, outcomes: Sequence[FakeProcess | OSError]) -> None:
+        self.outcomes = list(outcomes)
+        self.calls: list[tuple[tuple[Any, ...], dict[str, Any]]] = []
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> FakeProcess:
+        self.calls.append((args, kwargs))
+        outcome = self.outcomes.pop(0)
+        if isinstance(outcome, OSError):
+            raise outcome
+        return outcome
+
+    @property
+    def commands(self) -> list[tuple[Any, ...]]:
+        return [args for args, _ in self.calls]
+
+
+def install_recorder(
+    monkeypatch: pytest.MonkeyPatch,
+    outcomes: Sequence[FakeProcess | OSError],
+) -> CodeGraphProcessRecorder:
+    recorder = CodeGraphProcessRecorder(outcomes)
+    monkeypatch.setattr(
+        "agentci.integrations.codegraph.asyncio.create_subprocess_exec",
+        recorder,
+    )
+    return recorder
+
+
+@pytest.mark.parametrize(
+    ("database_exists", "initial_exclude", "expected_command", "expected_exclude"),
+    [
+        pytest.param(False, None, "init", ".codegraph/\n", id="incomplete-index"),
+        pytest.param(
+            True,
+            "# local excludes\n.codegraph/\n",
+            "sync",
+            "# local excludes\n.codegraph/\n",
+            id="existing-index",
+        ),
+    ],
+)
+async def test_prepare_selects_init_or_sync_and_updates_git_exclude(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    database_exists: bool,
+    initial_exclude: str | None,
+    expected_command: str,
+    expected_exclude: str,
 ) -> None:
     workspace = tmp_path / "repo"
     (workspace / ".git" / "info").mkdir(parents=True)
     (workspace / ".codegraph").mkdir()
-    calls: list[tuple[object, ...]] = []
+    if database_exists:
+        (workspace / ".codegraph" / "codegraph.db").touch()
+    exclude = workspace / ".git" / "info" / "exclude"
+    if initial_exclude is not None:
+        exclude.write_text(initial_exclude)
+    recorder = install_recorder(monkeypatch, [FakeProcess()])
 
-    async def create_subprocess_exec(*args, **_kwargs):
-        calls.append(args)
-        return FakeProcess()
+    await CodeGraph().prepare(workspace)
 
-    monkeypatch.setattr(
-        "agentci.adapters.codegraph.asyncio.create_subprocess_exec",
-        create_subprocess_exec,
+    assert recorder.commands == [("codegraph", expected_command, str(workspace))]
+    kwargs = recorder.calls[0][1]
+    assert kwargs["cwd"] == workspace
+    assert kwargs["env"]["CODEGRAPH_TELEMETRY"] == "0"
+    assert kwargs["stdout"] is asyncio.subprocess.PIPE
+    assert kwargs["stderr"] is asyncio.subprocess.PIPE
+    assert exclude.read_text() == expected_exclude
+
+
+@pytest.mark.parametrize(
+    ("initial", "expected"),
+    [
+        ("*.pyc", "*.pyc\n.codegraph/\n"),
+        ("# .codegraph/ is documented here\n", "# .codegraph/ is documented here\n.codegraph/\n"),
+        ("  .codegraph/  \n", "  .codegraph/  \n"),
+    ],
+)
+async def test_handles_exclude_file_boundaries(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    initial: str,
+    expected: str,
+) -> None:
+    workspace = tmp_path / "repo"
+    exclude = workspace / ".git" / "info" / "exclude"
+    exclude.parent.mkdir(parents=True)
+    exclude.write_text(initial)
+
+    install_recorder(monkeypatch, [FakeProcess()])
+
+    await CodeGraph().prepare(workspace)
+
+    assert exclude.read_text() == expected
+
+
+async def test_reports_missing_executable(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    workspace = tmp_path / "repo"
+    workspace.mkdir()
+
+    install_recorder(
+        monkeypatch,
+        [FileNotFoundError(2, "No such file or directory", "codegraph")],
     )
 
-    await CodeGraphClient().prepare(workspace)
+    with pytest.raises(CodeGraphError, match="Could not run CodeGraph:.*codegraph") as raised:
+        await CodeGraph().prepare(workspace)
 
-    assert calls == [("codegraph", "init", str(workspace))]
+    assert isinstance(raised.value.__cause__, FileNotFoundError)
     assert (workspace / ".git" / "info" / "exclude").read_text() == ".codegraph/\n"
 
 
-async def test_syncs_an_existing_index_without_duplicating_exclude(
-    tmp_path: Path, monkeypatch
+async def test_reports_nonzero_exit_with_bounded_non_utf8_stderr(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     workspace = tmp_path / "repo"
-    (workspace / ".git" / "info").mkdir(parents=True)
-    (workspace / ".codegraph").mkdir()
-    (workspace / ".codegraph" / "codegraph.db").touch()
-    exclude = workspace / ".git" / "info" / "exclude"
-    exclude.write_text("# local excludes\n.codegraph/\n")
-    calls: list[tuple[object, ...]] = []
+    workspace.mkdir()
+    stderr = b"discarded-prefix" + (b"x" * 1200) + b"\xff useful-tail"
 
-    async def create_subprocess_exec(*args, **_kwargs):
-        calls.append(args)
-        return FakeProcess()
-
-    monkeypatch.setattr(
-        "agentci.adapters.codegraph.asyncio.create_subprocess_exec",
-        create_subprocess_exec,
+    install_recorder(
+        monkeypatch,
+        [FakeProcess(returncode=7, stderr=stderr)],
     )
 
-    await CodeGraphClient().prepare(workspace)
+    with pytest.raises(CodeGraphError, match="codegraph init failed") as raised:
+        await CodeGraph().prepare(workspace)
 
-    assert calls == [("codegraph", "sync", str(workspace))]
-    assert exclude.read_text() == "# local excludes\n.codegraph/\n"
+    message = str(raised.value)
+    assert "discarded-prefix" not in message
+    assert "useful-tail" in message
+    assert len(message.removeprefix("codegraph init failed: ")) == 1000

tests/test_commands.py

@@ -1,38 +1,52 @@
 import pytest
 
-from agentci.domain.commands import CommandError, parse_command, resolve_job_kind
-from agentci.domain.models import CommandName, JobKind
+from agentci.engine.commands import CommandError, parse_command, resolve_job_kind
+from agentci.engine.model import CommandName, JobKind
 
 
 def test_ignores_non_commands() -> None:
     assert parse_command("please run /agent plan") is None
 
 
-@pytest.mark.parametrize("name", list(CommandName))
-@pytest.mark.parametrize("line_breaks", [1, 2, 5])
-def test_all_commands_accept_messages_after_any_number_of_lines(
-    name: CommandName, line_breaks: int
-) -> None:
-    command = parse_command(
-        f"/agent {name.value}{'\n' * line_breaks}"
-        "focus on the API\nand add tests"
-    )
-    assert command is not None
-    assert command.name is name
-    assert command.message == "focus on the API\nand add tests"
-
-
-@pytest.mark.parametrize("name", list(CommandName))
-def test_all_commands_accept_crlf_separated_multiline_messages(
+@pytest.mark.parametrize(
+    ("name", "is_pull_request", "expected_kind"),
+    [
+        (CommandName.PLAN, False, JobKind.PLAN),
+        (CommandName.DISCUSS, False, JobKind.DISCUSS),
+        (CommandName.IMPLEMENT, False, JobKind.IMPLEMENT),
+        (CommandName.ITERATE, False, JobKind.ITERATE_PLAN),
+        (CommandName.ITERATE, True, JobKind.ITERATE_IMPLEMENT),
+        (CommandName.FIX, True, JobKind.FIX),
+    ],
+)
+def test_supported_commands_parse_and_resolve(
     name: CommandName,
+    is_pull_request: bool,
+    expected_kind: JobKind,
 ) -> None:
-    command = parse_command(
-        f"/agent {name.value}\r\n\r\n\r\n"
-        "focus on the API\r\nand add tests"
-    )
+    command = parse_command(f"/agent {name.value}\nfocus on the API\nand add tests")
+
     assert command is not None
-    assert command.name is name
-    assert command.message == "focus on the API\r\nand add tests"
+    assert (command.name, command.message) == (
+        name,
+        "focus on the API\nand add tests",
+    )
+    assert resolve_job_kind(command, is_pull_request=is_pull_request) is expected_kind
+
+
+@pytest.mark.parametrize(
+    ("separator", "line_breaks"),
+    [("\n", 1), ("\n", 2), ("\n", 5), ("\r\n", 3)],
+)
+def test_multiline_messages_accept_line_separators(
+    separator: str,
+    line_breaks: int,
+) -> None:
+    message = f"focus on the API{separator}and add tests"
+    command = parse_command(f"/agent {CommandName.PLAN.value}{separator * line_breaks}{message}")
+
+    assert command is not None
+    assert (command.name, command.message) == (CommandName.PLAN, message)
 
 
 def test_discuss_requires_message() -> None:
@@ -40,11 +54,25 @@ def test_discuss_requires_message() -> None:
         parse_command("/agent discuss")
 
 
-def test_rejects_wrong_location() -> None:
-    command = parse_command("/agent fix")
+@pytest.mark.parametrize(
+    ("name", "is_pull_request", "error_match"),
+    [
+        (CommandName.FIX, False, "pull request"),
+        (CommandName.PLAN, True, "issue"),
+        (CommandName.DISCUSS, True, "issue"),
+        (CommandName.IMPLEMENT, True, "issue"),
+    ],
+)
+def test_rejects_wrong_location(
+    name: CommandName,
+    is_pull_request: bool,
+    error_match: str,
+) -> None:
+    command = parse_command(f"/agent {name.value} details")
     assert command is not None
-    with pytest.raises(CommandError, match="pull request"):
-        resolve_job_kind(command, is_pull_request=False)
+
+    with pytest.raises(CommandError, match=error_match):
+        resolve_job_kind(command, is_pull_request=is_pull_request)
 
 
 @pytest.mark.parametrize(
@@ -52,10 +80,6 @@ def test_rejects_wrong_location() -> None:
     [
         ("/agent iterate", ""),
         ("/agent iterate refine tests", "refine tests"),
-        (
-            "/agent iterate\n\nkeep the API stable\nlimit changes to the parser",
-            "keep the API stable\nlimit changes to the parser",
-        ),
     ],
 )
 def test_iterate_accepts_optional_message(body: str, message: str) -> None:
@@ -63,5 +87,3 @@ def test_iterate_accepts_optional_message(body: str, message: str) -> None:
     assert command is not None
     assert command.name is CommandName.ITERATE
     assert command.message == message
-    assert resolve_job_kind(command, is_pull_request=False) is JobKind.ITERATE_PLAN
-    assert resolve_job_kind(command, is_pull_request=True) is JobKind.ITERATE_IMPLEMENT

tests/test_config.py

@@ -1,49 +1,138 @@
+import os
+from pathlib import Path
+
 import pytest
 from pydantic import ValidationError
 
-from agentci.config import Settings
+from agentci.config.settings import Settings
 
 
-def test_parses_comma_delimited_install_scripts() -> None:
-    settings = Settings(
-        _env_file=None,  # type: ignore[call-arg]
-        install_scripts=" python, dotnet, company-tools, ",
+@pytest.fixture(autouse=True)
+def isolate_agentci_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    for name in tuple(os.environ):
+        if name.startswith("AGENTCI_"):
+            monkeypatch.delenv(name)
+
+
+def settings(**overrides: object) -> Settings:
+    return Settings(_env_file=None, **overrides)  # type: ignore[arg-type,call-arg]
+
+
+def test_reads_values_from_an_isolated_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AGENTCI_INSTALL_SCRIPTS", "python,dotnet")
+    monkeypatch.setenv("AGENTCI_MAX_CONCURRENT_JOBS", "7")
+
+    value = settings()
+
+    assert value.install_scripts == ["python", "dotnet"]
+    assert value.max_concurrent_jobs == 7
+
+
+@pytest.mark.parametrize("field", ["gitea_url", "opencode_url"])
+def test_normalizes_service_urls(field: str) -> None:
+    value = settings(**{field: "https://service.example/base///"})
+
+    assert getattr(value, field) == "https://service.example/base"
+
+
+@pytest.mark.parametrize(
+    ("field", "accepted", "rejected"),
+    [
+        ("plan_review_rounds", (1, 20), (0, 21)),
+        ("implement_review_rounds", (1, 20), (0, 21)),
+        ("turn_timeout_seconds", (60,), (59,)),
+        ("install_script_timeout_seconds", (1,), (0,)),
+        ("worker_poll_seconds", (0.1,), (0.09,)),
+        ("max_concurrent_jobs", (1, 32), (0, 33)),
+    ],
+)
+def test_enforces_documented_numeric_boundaries(
+    field: str,
+    accepted: tuple[int | float, ...],
+    rejected: tuple[int | float, ...],
+) -> None:
+    for value in accepted:
+        assert getattr(settings(**{field: value}), field) == value
+    for value in rejected:
+        with pytest.raises(ValidationError):
+            settings(**{field: value})
+
+
+def test_reads_and_strips_secret_files(tmp_path: Path) -> None:
+    token_file = tmp_path / "token"
+    webhook_file = tmp_path / "webhook"
+    password_file = tmp_path / "password"
+    token_file.write_text("  gitea-token\n")
+    webhook_file.write_text(" webhook-secret \n")
+    password_file.write_text("opencode-password\n")
+    value = settings(
+        gitea_token_file=token_file,
+        webhook_secret_file=webhook_file,
+        opencode_server_password_file=password_file,
     )
 
-    assert settings.install_scripts == ["python", "dotnet", "company-tools"]
+    assert value.gitea_token == "gitea-token"
+    assert value.webhook_secret == b"webhook-secret"
+    assert value.opencode_server_password == "opencode-password"
+
+
+def test_missing_secret_file_has_actionable_error(tmp_path: Path) -> None:
+    missing = tmp_path / "missing-token"
+    value = settings(gitea_token_file=missing)
+
+    with pytest.raises(RuntimeError, match="Cannot read Gitea token") as raised:
+        _ = value.gitea_token
+
+    assert str(missing) in str(raised.value)
+
+
+def test_empty_secret_file_is_rejected(tmp_path: Path) -> None:
+    empty = tmp_path / "webhook"
+    empty.write_text(" \n")
+    value = settings(webhook_secret_file=empty)
+
+    with pytest.raises(RuntimeError, match="webhook secret file") as raised:
+        _ = value.webhook_secret
+
+    assert str(empty) in str(raised.value)
+
+
+def test_derived_state_paths_follow_data_directory(tmp_path: Path) -> None:
+    data_dir = tmp_path / "state"
+    value = settings(data_dir=data_dir)
+
+    assert value.database_path == data_dir / "agentci.sqlite3"
+    assert value.workspaces_dir == data_dir / "workspaces"
 
 
 @pytest.mark.parametrize("value", ["../script", "tools/setup", "python,python"])
 def test_rejects_unsafe_or_duplicate_install_scripts(value: str) -> None:
     with pytest.raises(ValidationError):
-        Settings(_env_file=None, install_scripts=value)  # type: ignore[call-arg]
+        settings(install_scripts=value)
 
 
-def test_empty_install_scripts_disable_setup() -> None:
-    settings = Settings(
-        _env_file=None,  # type: ignore[call-arg]
-        install_scripts="",
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (" python, dotnet, company-tools, ", ["python", "dotnet", "company-tools"]),
+        ("", []),
+        (None, []),
+        ([], []),
+    ],
+)
+def test_normalizes_install_scripts(value: object, expected: list[str]) -> None:
+    assert settings(install_scripts=value).install_scripts == expected
+
+
+def test_agent_defaults_select_expected_capacity_and_research_models() -> None:
+    value = settings()
+
+    assert value.max_concurrent_jobs == 2
+    assert (value.explore_model, value.explore_variant) == (
+        "openai/gpt-5.6-luna",
+        "low",
     )
-    assert settings.install_scripts == []
-
-
-def test_defaults_research_variant_to_high() -> None:
-    settings = Settings(_env_file=None)  # type: ignore[call-arg]
-    assert settings.research_variant == "high"
-
-
-def test_defaults_explore_agent_to_luna_low() -> None:
-    settings = Settings(_env_file=None)  # type: ignore[call-arg]
-    assert settings.explore_model == "openai/gpt-5.6-luna"
-    assert settings.explore_variant == "low"
-
-
-def test_reads_comma_delimited_install_scripts_from_environment(monkeypatch) -> None:
-    monkeypatch.setenv("AGENTCI_INSTALL_SCRIPTS", "python,dotnet")
-
-    settings = Settings(_env_file=None)  # type: ignore[call-arg]
-
-    assert settings.install_scripts == ["python", "dotnet"]
+    assert value.research_variant == "high"
 
 
 @pytest.mark.parametrize(
@@ -51,4 +140,4 @@ def test_reads_comma_delimited_install_scripts_from_environment(monkeypatch) ->
 )
 def test_requires_provider_qualified_opencode_models(field: str) -> None:
     with pytest.raises(ValidationError, match="provider/model"):
-        Settings(_env_file=None, **{field: "model-only"})  # type: ignore[call-arg]
+        settings(**{field: "model-only"})

tests/test_context.py

@@ -1,8 +1,12 @@
-from agentci.adapters.gitea_models import CommentInfo, IssueInfo
-from agentci.workflows.context import ContextBuilder
+from typing import cast
+
+from agentci.engine.repository import Repository
+from agentci.integrations.gitea.client import Gitea
+from agentci.integrations.gitea.models import CommentInfo, IssueInfo, PullRequestInfo
+from agentci.workflows.context import build_issue_context, build_pull_request_context
 
 
-class FakeGitea:
+class FakeIssueGitea:
     async def issue(self, *_args):
         return IssueInfo(number=2, title="Broken widget", body="It fails.", state="open")
 
@@ -13,15 +17,185 @@ class FakeGitea:
         ]
 
 
-class FakeStorage:
+class FakeRepository:
     async def operational_comment_ids(self, *_args):
         return {2}
 
 
+class PopulatedPullRequestGitea:
+    async def pull_request(self, *_args):
+        return PullRequestInfo(
+            number=3,
+            title="Fix widget",
+            body="Fixes the failure.",
+            state="open",
+            merged=False,
+            base_branch="main",
+            head_branch="fix-widget",
+            head_sha="abcdef1234567890",
+            head_owner="alice",
+            head_repo="repo",
+        )
+
+    async def issue_comments(self, *_args):
+        return [
+            CommentInfo(
+                1,
+                "alice",
+                "First timeline comment: Please add a test.",
+                "2026-01-01",
+            ),
+            CommentInfo(2, "bob", "Second timeline comment", "2026-01-02"),
+        ]
+
+    async def pull_reviews(self, *_args):
+        return [
+            {
+                "id": 10,
+                "user": {"login": "carol"},
+                "state": "REQUEST_CHANGES",
+                "body": "First formal review: One issue remains.",
+            },
+            {
+                "id": 11,
+                "user": {"login": "dave"},
+                "state": "APPROVED",
+                "body": "Second formal review",
+            },
+        ]
+
+    async def review_comments(self, *_args):
+        review_id = _args[-1]
+        if review_id == 10:
+            return [
+                {
+                    "path": "src/old.py",
+                    "new_position": None,
+                    "old_position": 21,
+                    "body": "Old-side position",
+                }
+            ]
+        return [
+            {
+                "path": "src/new.py",
+                "new_position": 34,
+                "body": "New-side position",
+            },
+            {
+                "path": "src/widget.py",
+                "new_position": 12,
+                "body": "Handle the empty value.",
+            },
+        ]
+
+    async def pull_commits(self, *_args):
+        return [
+            {"sha": "111111111111aaaa", "commit": {"message": "First commit"}},
+            {"sha": "222222222222bbbb", "commit": {"message": "Second commit"}},
+        ]
+
+
+class EmptyIssueGitea:
+    async def issue(self, *_args):
+        return IssueInfo(number=5, title="Empty issue", body="", state="open")
+
+    async def issue_comments(self, *_args):
+        return []
+
+
+class EmptyRepository:
+    async def operational_comment_ids(self, *_args):
+        return set()
+
+
+class EmptyPullRequestGitea:
+    async def pull_request(self, *_args):
+        return PullRequestInfo(
+            number=6,
+            title="Empty pull request",
+            body="",
+            state="open",
+            merged=False,
+            base_branch="main",
+            head_branch="empty",
+            head_sha="1234567890abcdef",
+            head_owner="alice",
+            head_repo="repo",
+        )
+
+    async def issue_comments(self, *_args):
+        return []
+
+    async def pull_reviews(self, *_args):
+        return []
+
+    async def pull_commits(self, *_args):
+        return []
+
+    async def review_comments(self, *_args):
+        raise AssertionError("review comments should not be requested without reviews")
+
+
 async def test_issue_context_excludes_operational_comments() -> None:
-    builder = ContextBuilder(FakeGitea(), FakeStorage())  # type: ignore[arg-type]
-    context = await builder.issue_context("org", "repo", 2)
+    context = await build_issue_context(
+        cast(Gitea, FakeIssueGitea()),
+        cast(Repository, FakeRepository()),
+        "org",
+        "repo",
+        2,
+    )
+
     assert "Broken widget" in context
     assert "Details" in context
     assert "Agent job queued" not in context
 
+
+async def test_pull_request_context_includes_ordered_feedback_reviews_and_commits() -> None:
+    pull, context = await build_pull_request_context(
+        cast(Gitea, PopulatedPullRequestGitea()), "org", "repo", 3
+    )
+
+    assert pull == PullRequestInfo(
+        number=3,
+        title="Fix widget",
+        body="Fixes the failure.",
+        state="open",
+        merged=False,
+        base_branch="main",
+        head_branch="fix-widget",
+        head_sha="abcdef1234567890",
+        head_owner="alice",
+        head_repo="repo",
+    )
+    assert "Please add a test." in context
+    assert "One issue remains." in context
+    assert context.index("First timeline comment") < context.index("Second timeline comment")
+    assert context.index("111111111111 First commit") < context.index("222222222222 Second commit")
+    assert context.index("Review 10 by carol") < context.index("Review 11 by dave")
+    assert "`src/old.py:21`: Old-side position" in context
+    assert "`src/new.py:34`: New-side position" in context
+    assert "`src/widget.py:12`: Handle the empty value." in context
+
+
+async def test_issue_context_labels_empty_body_and_discussion() -> None:
+    context = await build_issue_context(
+        cast(Gitea, EmptyIssueGitea()),
+        cast(Repository, EmptyRepository()),
+        "org",
+        "repo",
+        5,
+    )
+
+    assert "## Issue body\n(empty)" in context
+    assert "## Discussion\n(none)" in context
+
+
+async def test_pull_request_context_labels_empty_sections() -> None:
+    _, context = await build_pull_request_context(
+        cast(Gitea, EmptyPullRequestGitea()), "org", "repo", 6
+    )
+
+    assert "## Pull request body\n(empty)" in context
+    assert "## Commits\n(none)" in context
+    assert "## Timeline discussion\n(none)" in context
+    assert "## Formal and inline reviews\n(none)" in context

tests/test_development.py

@@ -1,14 +1,15 @@
+import asyncio
 from pathlib import Path
 
 import pytest
 
-from agentci.adapters.development import (
+from agentci.integrations.development import (
     DevelopmentEnvironment,
     DevelopmentEnvironmentError,
 )
 
 
-def environment(
+def development_environment(
     tmp_path: Path, scripts: list[str], *, timeout_seconds: int = 5
 ) -> DevelopmentEnvironment:
     scripts_dir = tmp_path / "scripts"
@@ -23,22 +24,29 @@ def environment(
     )
 
 
-def script(path: Path, body: str) -> None:
+def shell_script(path: Path, body: str, *, executable: bool = True) -> None:
     path.write_text(f"#!/bin/sh\nset -eu\n{body}\n")
-    path.chmod(0o755)
+    path.chmod(0o755 if executable else 0o644)
+
+
+@pytest.fixture
+def workspace(tmp_path: Path) -> Path:
+    path = tmp_path / "workspace"
+    path.mkdir()
+    return path
 
 
 async def test_runs_custom_scripts_in_order_with_sanitized_environment(
-    tmp_path, monkeypatch
+    tmp_path: Path,
+    workspace: Path,
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    workspace = tmp_path / "workspace"
-    workspace.mkdir()
-    development = environment(tmp_path, ["first", "second"])
-    script(
+    development = development_environment(tmp_path, ["first", "second"])
+    shell_script(
         development.scripts_dir / "first",
-        "printf 'first:%s:%s\\n' \"$DEV_TOOLS_DIR\" \"${AGENTCI_SECRET-unset}\" >> order",
+        'printf \'first:%s:%s\\n\' "$DEV_TOOLS_DIR" "${AGENTCI_SECRET-unset}" >> order',
     )
-    script(development.scripts_dir / "second", "printf 'second\\n' >> order")
+    shell_script(development.scripts_dir / "second", "printf 'second\\n' >> order")
     monkeypatch.setenv("AGENTCI_SECRET", "must-not-leak")
 
     await development.prepare(workspace)
@@ -50,45 +58,125 @@ async def test_runs_custom_scripts_in_order_with_sanitized_environment(
     assert (tmp_path / "tools" / "bin").is_dir()
 
 
-async def test_supplied_script_names_use_the_same_directory(tmp_path) -> None:
-    workspace = tmp_path / "workspace"
-    workspace.mkdir()
-    development = environment(tmp_path, ["python"])
-    script(development.scripts_dir / "python", "printf 'python\\n' > selected")
-
-    await development.prepare(workspace)
-
-    assert (workspace / "selected").read_text() == "python\n"
-
-
-async def test_runs_non_executable_shell_script_from_bind_mount(tmp_path) -> None:
-    workspace = tmp_path / "workspace"
-    workspace.mkdir()
-    development = environment(tmp_path, ["mounted"])
-    mounted = development.scripts_dir / "mounted"
-    mounted.write_text("#!/bin/sh\nprintf 'mounted\\n' > selected\n")
-    mounted.chmod(0o644)
+async def test_runs_non_executable_shell_script_from_bind_mount(
+    tmp_path: Path,
+    workspace: Path,
+) -> None:
+    development = development_environment(tmp_path, ["mounted"])
+    shell_script(
+        development.scripts_dir / "mounted",
+        "printf 'mounted\\n' > selected",
+        executable=False,
+    )
 
     await development.prepare(workspace)
 
     assert (workspace / "selected").read_text() == "mounted\n"
 
 
-async def test_reports_script_failure_output(tmp_path) -> None:
-    workspace = tmp_path / "workspace"
-    workspace.mkdir()
-    development = environment(tmp_path, ["broken"])
-    script(development.scripts_dir / "broken", "printf 'failed detail' >&2; exit 7")
+async def test_serializes_concurrent_preparation(tmp_path, monkeypatch) -> None:
+    development = development_environment(tmp_path, ["shared"])
+    shell_script(development.scripts_dir / "shared", "true")
+    started = asyncio.Event()
+    release = asyncio.Event()
+    active = 0
+    maximum_active = 0
+
+    async def run(*_args) -> None:
+        nonlocal active, maximum_active
+        active += 1
+        maximum_active = max(maximum_active, active)
+        started.set()
+        await release.wait()
+        active -= 1
+
+    monkeypatch.setattr(development, "_run", run)
+    first = asyncio.create_task(development.prepare(tmp_path / "first"))
+    await started.wait()
+    second = asyncio.create_task(development.prepare(tmp_path / "second"))
+    await asyncio.sleep(0)
+    release.set()
+    await asyncio.gather(first, second)
+
+    assert maximum_active == 1
+
+
+async def test_reports_missing_install_script(tmp_path: Path, workspace: Path) -> None:
+    development = development_environment(tmp_path, ["missing"])
+
+    with pytest.raises(
+        DevelopmentEnvironmentError,
+        match=r"Install script 'missing' was not found",
+    ):
+        await development.prepare(workspace)
+
+
+async def test_stops_after_failure_and_reports_output(
+    tmp_path: Path,
+    workspace: Path,
+) -> None:
+    development = development_environment(tmp_path, ["first", "second"])
+    shell_script(
+        development.scripts_dir / "first",
+        "printf 'first\\n' > first-ran; printf 'failed detail' >&2; exit 7",
+    )
+    shell_script(development.scripts_dir / "second", "printf 'second\\n' > second-ran")
 
     with pytest.raises(DevelopmentEnvironmentError, match="exited with 7: failed detail"):
         await development.prepare(workspace)
 
+    assert (workspace / "first-ran").read_text() == "first\n"
+    assert not (workspace / "second-ran").exists()
 
-async def test_times_out_install_script(tmp_path) -> None:
-    workspace = tmp_path / "workspace"
-    workspace.mkdir()
-    development = environment(tmp_path, ["slow"], timeout_seconds=1)
-    script(development.scripts_dir / "slow", "exec sleep 10")
+
+async def test_failure_output_keeps_only_bounded_tail(
+    tmp_path: Path,
+    workspace: Path,
+) -> None:
+    development = development_environment(tmp_path, ["verbose"])
+    shell_script(
+        development.scripts_dir / "verbose",
+        "printf 'discarded-prefix' >&2; "
+        'i=0; while [ "$i" -lt 2100 ]; do printf x >&2; i=$((i + 1)); done; '
+        "printf 'useful-tail' >&2; exit 9",
+    )
+
+    with pytest.raises(DevelopmentEnvironmentError) as raised:
+        await development.prepare(workspace)
+
+    message = str(raised.value)
+    assert "discarded-prefix" not in message
+    assert message.endswith("useful-tail")
+
+
+async def test_wraps_subprocess_start_error(
+    tmp_path: Path,
+    workspace: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    development = development_environment(tmp_path, ["broken"])
+    shell_script(development.scripts_dir / "broken", "true")
+
+    async def create_subprocess_exec(*_args, **_kwargs):
+        raise OSError("exec unavailable")
+
+    monkeypatch.setattr(
+        "agentci.integrations.development.asyncio.create_subprocess_exec",
+        create_subprocess_exec,
+    )
+
+    with pytest.raises(
+        DevelopmentEnvironmentError,
+        match="Could not run install script 'broken': exec unavailable",
+    ) as raised:
+        await development.prepare(workspace)
+
+    assert isinstance(raised.value.__cause__, OSError)
+
+
+async def test_times_out_install_script(tmp_path: Path, workspace: Path) -> None:
+    development = development_environment(tmp_path, ["slow"], timeout_seconds=1)
+    shell_script(development.scripts_dir / "slow", "exec sleep 10")
 
     with pytest.raises(DevelopmentEnvironmentError, match="exceeded 1 seconds"):
         await development.prepare(workspace)

tests/test_git.py

@@ -0,0 +1,247 @@
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from agentci.integrations.git import Git, GitError
+
+
+class FakeProcess:
+    def __init__(
+        self,
+        stdout: bytes = b"",
+        stderr: bytes = b"",
+        returncode: int = 0,
+    ) -> None:
+        self.stdout = stdout
+        self.stderr = stderr
+        self.returncode = returncode
+
+    async def communicate(self) -> tuple[bytes, bytes]:
+        return self.stdout, self.stderr
+
+
+class SubprocessRecorder:
+    def __init__(self, outcomes: Sequence[FakeProcess | OSError]) -> None:
+        self.outcomes = list(outcomes)
+        self.calls: list[tuple[tuple[Any, ...], dict[str, Any]]] = []
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> FakeProcess:
+        self.calls.append((args, kwargs))
+        outcome = self.outcomes.pop(0)
+        if isinstance(outcome, OSError):
+            raise outcome
+        return outcome
+
+    @property
+    def commands(self) -> list[tuple[Any, ...]]:
+        return [args for args, _ in self.calls]
+
+
+def git_client(tmp_path: Path) -> Git:
+    return Git(
+        gitea_url="https://git.example.test/",
+        username="agent-user",
+        token="secret-token",
+        askpass_path=tmp_path / "askpass.sh",
+        commit_name="Agent CI",
+        commit_email="agent@example.test",
+    )
+
+
+def install_recorder(
+    monkeypatch: pytest.MonkeyPatch,
+    outcomes: Sequence[FakeProcess | OSError],
+) -> SubprocessRecorder:
+    recorder = SubprocessRecorder(outcomes)
+    monkeypatch.setattr(asyncio, "create_subprocess_exec", recorder)
+    return recorder
+
+
+async def test_clone_uses_authenticated_remote_and_returns_head(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    for name in (
+        "GIT_ASKPASS",
+        "GIT_TERMINAL_PROMPT",
+        "AGENTCI_GIT_USERNAME",
+        "AGENTCI_GIT_PASSWORD",
+    ):
+        monkeypatch.delenv(name, raising=False)
+    recorder = install_recorder(
+        monkeypatch,
+        [FakeProcess(), FakeProcess(stdout=b"abc123\n")],
+    )
+    destination = tmp_path / "workspaces" / "repo"
+
+    sha = await git_client(tmp_path).clone("org", "repo", "main", destination)
+
+    assert sha == "abc123"
+    assert destination.parent.is_dir()
+    assert recorder.commands == [
+        (
+            "git",
+            "clone",
+            "--branch",
+            "main",
+            "--single-branch",
+            "https://git.example.test/org/repo.git",
+            str(destination),
+        ),
+        ("git", "rev-parse", "HEAD"),
+    ]
+    clone_kwargs = recorder.calls[0][1]
+    assert clone_kwargs["cwd"] == destination.parent
+    assert clone_kwargs["stdout"] is asyncio.subprocess.PIPE
+    assert clone_kwargs["stderr"] is asyncio.subprocess.PIPE
+    assert (
+        clone_kwargs["env"]
+        | {
+            "GIT_ASKPASS": str(tmp_path / "askpass.sh"),
+            "GIT_TERMINAL_PROMPT": "0",
+            "AGENTCI_GIT_USERNAME": "agent-user",
+            "AGENTCI_GIT_PASSWORD": "secret-token",
+        }
+        == clone_kwargs["env"]
+    )
+    current_sha_environment = recorder.calls[1][1]["env"]
+    assert "AGENTCI_GIT_PASSWORD" not in current_sha_environment
+
+
+async def test_sync_branch_resets_and_cleans_before_returning_sha(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    recorder = install_recorder(
+        monkeypatch,
+        [FakeProcess(), FakeProcess(), FakeProcess(), FakeProcess(stdout=b"new-sha\n")],
+    )
+    workspace = tmp_path / "repo"
+
+    sha = await git_client(tmp_path).sync_branch(workspace, "feature")
+
+    assert sha == "new-sha"
+    assert recorder.commands == [
+        (
+            "git",
+            "fetch",
+            "origin",
+            "refs/heads/feature:refs/remotes/origin/feature",
+        ),
+        ("git", "reset", "--hard", "origin/feature"),
+        ("git", "clean", "-fd"),
+        ("git", "rev-parse", "HEAD"),
+    ]
+    assert all(call[1]["cwd"] == workspace for call in recorder.calls)
+    assert recorder.calls[0][1]["env"]["AGENTCI_GIT_PASSWORD"] == "secret-token"
+
+
+async def test_local_worktree_commands_and_status_mapping(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    recorder = install_recorder(
+        monkeypatch,
+        [
+            FakeProcess(),
+            FakeProcess(stdout=b" M src/app.py\n"),
+            FakeProcess(stdout=b" \n"),
+            FakeProcess(),
+        ],
+    )
+    workspace = tmp_path / "repo"
+    git = git_client(tmp_path)
+
+    await git.create_branch(workspace, "agent/issue-1")
+    dirty = await git.has_changes(workspace)
+    clean = await git.has_changes(workspace)
+    await git.diff_check(workspace)
+
+    assert dirty is True
+    assert clean is False
+    assert recorder.commands == [
+        ("git", "switch", "-c", "agent/issue-1"),
+        ("git", "status", "--porcelain"),
+        ("git", "status", "--porcelain"),
+        ("git", "diff", "--check"),
+    ]
+
+
+async def test_commit_stages_all_changes_sets_identity_and_returns_sha(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    recorder = install_recorder(
+        monkeypatch,
+        [FakeProcess(), FakeProcess(), FakeProcess(stdout=b"commit-sha\n")],
+    )
+    workspace = tmp_path / "repo"
+
+    sha = await git_client(tmp_path).commit(workspace, "agent: Fix widget")
+
+    assert sha == "commit-sha"
+    assert recorder.commands == [
+        ("git", "add", "-A"),
+        (
+            "git",
+            "-c",
+            "user.name=Agent CI",
+            "-c",
+            "user.email=agent@example.test",
+            "commit",
+            "-m",
+            "agent: Fix widget",
+        ),
+        ("git", "rev-parse", "HEAD"),
+    ]
+
+
+async def test_push_command_supports_initial_and_existing_branches(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    recorder = install_recorder(monkeypatch, [FakeProcess(), FakeProcess()])
+    workspace = tmp_path / "repo"
+    git = git_client(tmp_path)
+
+    await git.push(workspace, "agent/new", set_upstream=True)
+    await git.push(workspace, "agent/existing")
+
+    assert recorder.commands == [
+        ("git", "push", "--set-upstream", "origin", "agent/new"),
+        ("git", "push", "origin", "HEAD:agent/existing"),
+    ]
+    assert all(call[1]["env"]["GIT_TERMINAL_PROMPT"] == "0" for call in recorder.calls)
+
+
+async def test_git_translates_process_start_failure(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_recorder(monkeypatch, [OSError("git executable missing")])
+
+    with pytest.raises(GitError, match="Could not run git rev-parse") as error:
+        await git_client(tmp_path).current_sha(tmp_path / "repo")
+
+    assert isinstance(error.value.__cause__, OSError)
+
+
+async def test_git_translates_nonzero_exit_and_stderr(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_recorder(
+        monkeypatch,
+        [FakeProcess(stderr=b"fatal: invalid diff\n", returncode=2)],
+    )
+
+    with pytest.raises(GitError, match="git diff failed: fatal: invalid diff"):
+        await git_client(tmp_path).diff_check(tmp_path / "repo")
+
+
+async def test_commit_failure_identifies_commit_operation(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_recorder(
+        monkeypatch,
+        [FakeProcess(), FakeProcess(stderr=b"nothing to commit\n", returncode=1)],
+    )
+
+    with pytest.raises(GitError, match="git commit failed: nothing to commit"):
+        await git_client(tmp_path).commit(tmp_path / "repo", "agent: change")

tests/test_gitea.py

@@ -1,22 +1,339 @@
 import json
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from contextlib import asynccontextmanager
 
 import httpx
-import respx
+import pytest
 
-from agentci.adapters.gitea import GiteaClient
+from agentci.integrations.gitea.client import Gitea, GiteaError
+from agentci.integrations.gitea.models import CommentInfo, IssueInfo, PullRequestInfo
+
+Handler = Callable[[httpx.Request], Coroutine[None, None, httpx.Response]]
 
 
-@respx.mock
-async def test_updates_issue_comment_by_id() -> None:
-    route = respx.patch(
-        "https://gitea.example/api/v1/repos/org/repo/issues/comments/17"
-    ).mock(return_value=httpx.Response(200, json={"id": 17}))
-    client = GiteaClient("https://gitea.example", "secret")
-
+@asynccontextmanager
+async def gitea_client(handler: Handler, *, retries: int = 3) -> AsyncGenerator[Gitea]:
+    client = Gitea(
+        "https://gitea.example/",
+        "secret",
+        retries=retries,
+        transport=httpx.MockTransport(handler),
+    )
     try:
-        await client.update_comment("org", "repo", 17, "updated status")
+        yield client
     finally:
         await client.close()
 
-    assert route.called
-    assert json.loads(route.calls[0].request.content) == {"body": "updated status"}
+
+@pytest.fixture
+def recorded_backoffs(monkeypatch: pytest.MonkeyPatch) -> list[int]:
+    backoffs: list[int] = []
+
+    async def record_backoff(delay: int) -> None:
+        backoffs.append(delay)
+
+    monkeypatch.setattr("agentci.integrations.gitea.client.asyncio.sleep", record_backoff)
+    return backoffs
+
+
+async def test_sends_authenticated_json_request_contract() -> None:
+    requests: list[httpx.Request] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(200, json={"id": 17})
+
+    async with gitea_client(handler) as client:
+        assert await client.update_comment("org", "repo", 17, "updated status")
+
+    assert len(requests) == 1
+    request = requests[0]
+    assert request.method == "PATCH"
+    assert request.url == httpx.URL(
+        "https://gitea.example/api/v1/repos/org/repo/issues/comments/17"
+    )
+    assert request.headers["authorization"] == "token secret"
+    assert request.headers["accept"] == "application/json"
+    assert request.headers["content-type"] == "application/json"
+    assert json.loads(request.content) == {"body": "updated status"}
+
+
+@pytest.mark.parametrize(
+    ("permission", "expected"),
+    [("write", True), ("ADMIN", True), ("owner", True), ("read", False), (None, False)],
+)
+async def test_maps_repository_permissions(permission: str | None, expected: bool) -> None:
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/v1/repos/org/repo/collaborators/alice/permission"
+        return httpx.Response(200, json={"permission": permission})
+
+    async with gitea_client(handler) as client:
+        assert await client.has_write_permission("org", "repo", "alice") is expected
+
+
+async def test_maps_issue_and_pull_request_responses() -> None:
+    async def handler(request: httpx.Request) -> httpx.Response:
+        match request.url.path:
+            case "/api/v1/repos/org/repo":
+                return httpx.Response(200, json={"default_branch": "trunk"})
+            case "/api/v1/repos/org/repo/issues/12":
+                return httpx.Response(
+                    200,
+                    json={"title": "Issue title", "body": None, "state": "open"},
+                )
+            case "/api/v1/repos/org/repo/pulls/8":
+                return httpx.Response(
+                    200,
+                    json={
+                        "title": "Pull title",
+                        "body": None,
+                        "state": "open",
+                        "merged": False,
+                        "base": {"ref": "trunk"},
+                        "head": {
+                            "ref": "feature",
+                            "sha": "abc123",
+                            "repo": {"owner": {"login": "fork-owner"}, "name": "fork"},
+                        },
+                    },
+                )
+        raise AssertionError(f"unexpected request: {request.url}")
+
+    async with gitea_client(handler) as client:
+        branch = await client.default_branch("org", "repo")
+        issue = await client.issue("org", "repo", 12)
+        pull = await client.pull_request("org", "repo", 8)
+
+    assert branch == "trunk"
+    assert issue == IssueInfo(number=12, title="Issue title", body="", state="open")
+    assert pull == PullRequestInfo(
+        number=8,
+        title="Pull title",
+        body="",
+        state="open",
+        merged=False,
+        base_branch="trunk",
+        head_branch="feature",
+        head_sha="abc123",
+        head_owner="fork-owner",
+        head_repo="fork",
+    )
+    assert pull.is_open
+
+
+async def test_creates_comment_and_pull_request_with_expected_payloads() -> None:
+    requests: list[httpx.Request] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path.endswith("/issues/4/comments"):
+            return httpx.Response(201, json={"id": "23"})
+        if request.method == "POST" and request.url.path.endswith("/pulls"):
+            return httpx.Response(201, json={"number": 9})
+        if request.method == "GET" and request.url.path.endswith("/pulls/9"):
+            return httpx.Response(
+                200,
+                json={
+                    "title": "Implement it",
+                    "body": "Details",
+                    "state": "open",
+                    "merged": False,
+                    "base": {"ref": "main"},
+                    "head": {
+                        "ref": "agent/work",
+                        "sha": "def456",
+                        "repo": {"owner": {"login": "org"}, "name": "repo"},
+                    },
+                },
+            )
+        raise AssertionError(f"unexpected request: {request.method} {request.url}")
+
+    async with gitea_client(handler) as client:
+        comment_id = await client.create_comment("org", "repo", 4, "Working")
+        pull = await client.create_pull_request(
+            "org",
+            "repo",
+            title="Implement it",
+            body="Details",
+            head="agent/work",
+            base="main",
+        )
+
+    assert comment_id == 23
+    assert pull.number == 9
+    assert [(request.method, request.url.path) for request in requests] == [
+        ("POST", "/api/v1/repos/org/repo/issues/4/comments"),
+        ("POST", "/api/v1/repos/org/repo/pulls"),
+        ("GET", "/api/v1/repos/org/repo/pulls/9"),
+    ]
+    assert json.loads(requests[0].content) == {"body": "Working"}
+    assert json.loads(requests[1].content) == {
+        "title": "Implement it",
+        "body": "Details",
+        "head": "agent/work",
+        "base": "main",
+    }
+
+
+async def test_maps_allowed_not_found_responses_without_retry() -> None:
+    paths: list[str] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        paths.append(request.url.path)
+        return httpx.Response(404)
+
+    async with gitea_client(handler) as client:
+        updated = await client.update_comment("org", "repo", 99, "missing")
+        comments = await client.review_comments("org", "repo", 7, 3)
+
+    assert not updated
+    assert comments == []
+    assert paths == [
+        "/api/v1/repos/org/repo/issues/comments/99",
+        "/api/v1/repos/org/repo/pulls/7/reviews/3/comments",
+    ]
+
+
+@pytest.mark.parametrize(("first_page_size", "expected_pages"), [(0, [1]), (49, [1]), (50, [1, 2])])
+async def test_pagination_stops_only_after_a_short_page(
+    first_page_size: int, expected_pages: list[int]
+) -> None:
+    pages: list[int] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/v1/repos/org/repo/issues/6/comments"
+        assert request.url.params["limit"] == "50"
+        page = int(request.url.params["page"])
+        pages.append(page)
+        size = first_page_size if page == 1 else 1
+        offset = 0 if page == 1 else 50
+        return httpx.Response(
+            200,
+            json=[
+                {
+                    "id": offset + index + 1,
+                    "user": {"login": f"user-{offset + index + 1}"},
+                    "body": None,
+                    "created_at": None,
+                }
+                for index in range(size)
+            ],
+        )
+
+    async with gitea_client(handler) as client:
+        comments = await client.issue_comments("org", "repo", 6)
+
+    expected_count = first_page_size + (1 if first_page_size == 50 else 0)
+    assert pages == expected_pages
+    assert len(comments) == expected_count
+    if comments:
+        assert comments[0] == CommentInfo(id=1, author="user-1", body="", created_at="")
+        assert comments[-1].id == expected_count
+
+
+@pytest.mark.parametrize("status", [400, 401, 403, 404, 422])
+async def test_nonretryable_status_fails_once(
+    status: int,
+    recorded_backoffs: list[int],
+) -> None:
+    attempts = 0
+
+    async def handler(_request: httpx.Request) -> httpx.Response:
+        nonlocal attempts
+        attempts += 1
+        return httpx.Response(status)
+
+    async with gitea_client(handler) as client:
+        with pytest.raises(
+            GiteaError,
+            match=rf"Gitea returned {status} for GET /repos/org/repo",
+        ):
+            await client.default_branch("org", "repo")
+
+    assert attempts == 1
+    assert recorded_backoffs == []
+
+
+@pytest.mark.parametrize(
+    ("status", "failures", "expected_backoffs"),
+    [
+        (429, 1, [1]),
+        (500, 1, [1]),
+        (502, 1, [1]),
+        (503, 1, [1]),
+        (504, 1, [1]),
+        pytest.param(None, 2, [1, 2], id="transport"),
+    ],
+)
+async def test_retryable_failure_recovers_after_exponential_backoff(
+    status: int | None,
+    failures: int,
+    expected_backoffs: list[int],
+    recorded_backoffs: list[int],
+) -> None:
+    attempts = 0
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal attempts
+        attempts += 1
+        if attempts <= failures:
+            if status is None:
+                raise httpx.ConnectError("connection refused", request=request)
+            return httpx.Response(status)
+        return httpx.Response(200, json={"default_branch": "main"})
+
+    async with gitea_client(handler) as client:
+        assert await client.default_branch("org", "repo") == "main"
+
+    assert attempts == failures + 1
+    assert recorded_backoffs == expected_backoffs
+
+
+@pytest.mark.parametrize(
+    ("status", "retries", "expected_message", "expected_cause", "expected_backoffs"),
+    [
+        pytest.param(
+            503,
+            3,
+            "Gitea remained unavailable for GET /repos/org/repo",
+            None,
+            [1, 2],
+            id="status",
+        ),
+        pytest.param(
+            None,
+            2,
+            "Gitea request failed: GET /repos/org/repo",
+            httpx.ConnectError,
+            [1],
+            id="transport",
+        ),
+    ],
+)
+async def test_retry_exhaustion_reports_failure(
+    status: int | None,
+    retries: int,
+    expected_message: str,
+    expected_cause: type[BaseException] | None,
+    expected_backoffs: list[int],
+    recorded_backoffs: list[int],
+) -> None:
+    attempts = 0
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal attempts
+        attempts += 1
+        if status is None:
+            raise httpx.ConnectError("connection refused", request=request)
+        return httpx.Response(status)
+
+    async with gitea_client(handler, retries=retries) as client:
+        with pytest.raises(GiteaError, match=expected_message) as raised:
+            await client.default_branch("org", "repo")
+
+    if expected_cause is None:
+        assert raised.value.__cause__ is None
+    else:
+        assert isinstance(raised.value.__cause__, expected_cause)
+    assert attempts == retries
+    assert recorded_backoffs == expected_backoffs

tests/test_health.py

@@ -0,0 +1,77 @@
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient, Response
+
+from agentci.api.routes.health import router
+
+
+class Provider:
+    def __init__(self, result: bool | Exception) -> None:
+        self.result = result
+        self.calls = 0
+
+    async def ready(self) -> bool:
+        self.calls += 1
+        if isinstance(self.result, Exception):
+            raise self.result
+        return self.result
+
+
+def application(provider: Provider | None = None) -> FastAPI:
+    app = FastAPI()
+    app.include_router(router)
+    if provider is not None:
+        app.state.runtime = SimpleNamespace(opencode=provider)
+    return app
+
+
+async def get(app: FastAPI, path: str) -> Response:
+    async with AsyncClient(
+        transport=ASGITransport(app=app, raise_app_exceptions=False),
+        base_url="http://test",
+    ) as client:
+        return await client.get(path)
+
+
+async def test_liveness_does_not_depend_on_runtime_providers() -> None:
+    response = await get(application(), "/health/live")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "live"}
+
+
+@pytest.mark.parametrize(
+    ("provider_result", "status_code", "payload"),
+    [
+        (True, 200, {"status": "ready"}),
+        (
+            False,
+            503,
+            {
+                "status": "not-ready",
+                "reason": "opencode provider is not connected",
+            },
+        ),
+        pytest.param(
+            RuntimeError("provider check failed"),
+            500,
+            None,
+            id="provider-error",
+        ),
+    ],
+)
+async def test_readiness_reflects_provider_state(
+    provider_result: bool | Exception,
+    status_code: int,
+    payload: dict[str, str] | None,
+) -> None:
+    provider = Provider(provider_result)
+
+    response = await get(application(provider), "/health/ready")
+
+    assert response.status_code == status_code
+    if payload is not None:
+        assert response.json() == payload
+    assert provider.calls == 1

tests/test_implementation_setup.py

@@ -1,143 +0,0 @@
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-from agentci.adapters.gitea_models import IssueInfo, PullRequestInfo, RepositoryInfo
-from agentci.domain.models import Job, JobKind, Workflow, WorkflowKind, WorkflowStatus
-from agentci.workflows.implement import ImplementWorkflow
-from agentci.workflows.pull_request import PullRequestWorkflow
-
-
-class SetupReached(RuntimeError):
-    pass
-
-
-class FakeDevelopment:
-    description = "python"
-
-    def __init__(self, events: list[str]) -> None:
-        self.events = events
-
-    async def prepare(self, _workspace: Path) -> None:
-        self.events.append("prepare")
-        raise SetupReached
-
-
-class FakeGit:
-    def __init__(self, events: list[str]) -> None:
-        self.events = events
-
-    async def clone(self, *_args) -> str:
-        self.events.append("clone")
-        return "base-sha"
-
-    async def create_branch(self, *_args) -> None:
-        self.events.append("create branch")
-
-    async def sync_branch(self, *_args) -> None:
-        self.events.append("sync branch")
-
-
-class FakeStorage:
-    def __init__(self, workflow: Workflow | None = None) -> None:
-        self.workflow = workflow
-
-    async def implementation_workflows(self, *_args):
-        return []
-
-    async def create_workflow(self, _workflow) -> None:
-        return None
-
-    async def update_job(self, *_args, **_kwargs) -> None:
-        return None
-
-    async def workflow_for_pr(self, *_args):
-        return self.workflow
-
-
-class FakeContext:
-    def __init__(self, pull: PullRequestInfo) -> None:
-        self.pull = pull
-
-    async def pull_request_context(self, *_args):
-        return self.pull, "context"
-
-
-class FakeGitea:
-    async def repository(self, *_args) -> RepositoryInfo:
-        return RepositoryInfo("org", "repo", "org/repo", "main")
-
-    async def issue(self, *_args) -> IssueInfo:
-        return IssueInfo(1, "Issue", "Body", "open")
-
-
-def job(kind: JobKind, *, pr_number: int | None = None) -> Job:
-    return Job(
-        id="job",
-        kind=kind,
-        target_key="org/repo:target",
-        repo_owner="org",
-        repo_name="repo",
-        issue_number=1,
-        pr_number=pr_number,
-        requester="alice",
-        message="",
-        comment_id=1,
-    )
-
-
-def pull() -> PullRequestInfo:
-    return PullRequestInfo(2, "PR", "Body", "open", False, "main", "agent", "sha", "org", "repo")
-
-
-async def test_initial_implementation_prepares_after_clone_and_branch(tmp_path) -> None:
-    events: list[str] = []
-    settings = SimpleNamespace(branch_prefix="agent", workspaces_dir=tmp_path)
-    deps = SimpleNamespace(
-        settings=settings,
-        storage=FakeStorage(),
-        gitea=FakeGitea(),
-        git=FakeGit(events),
-        development=FakeDevelopment(events),
-    )
-
-    with pytest.raises(SetupReached):
-        await ImplementWorkflow(deps).run(job(JobKind.IMPLEMENT))  # type: ignore[arg-type]
-
-    assert events == ["clone", "create branch", "prepare"]
-
-
-@pytest.mark.parametrize("operation", ["iterate", "fix"])
-async def test_pull_request_implementation_prepares_after_checkout(
-    tmp_path, operation: str
-) -> None:
-    events: list[str] = []
-    existing = Workflow(
-        id="flow",
-        kind=WorkflowKind.IMPLEMENT,
-        repo_owner="org",
-        repo_name="repo",
-        issue_number=1,
-        workspace_path=tmp_path / "repo",
-        base_sha="base",
-        branch="agent",
-        primary_session_id="primary",
-        reviewer_session_id="reviewer",
-        status=WorkflowStatus.COMPLETED,
-    )
-    settings = SimpleNamespace(workspaces_dir=tmp_path)
-    deps = SimpleNamespace(
-        settings=settings,
-        storage=FakeStorage(existing),
-        context=FakeContext(pull()),
-        git=FakeGit(events),
-        development=FakeDevelopment(events),
-    )
-    workflow = PullRequestWorkflow(deps)  # type: ignore[arg-type]
-
-    with pytest.raises(SetupReached):
-        await getattr(workflow, operation)(job(JobKind.FIX, pr_number=2))
-
-    expected_checkout = "sync branch" if operation == "iterate" else "clone"
-    assert events == [expected_checkout, "prepare"]