fix: restore governed capability and exact branch contracts

active-runtime/app/aios_agent_task_api.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""HTTP API for AIOS external-agent online task distribution.
+
+The service is intended to bind to loopback and be published through the
+existing TLS reverse proxy. Control operations use a server-managed control
+Bearer token. Agents receive individual Bearer tokens at registration; only
+token hashes are persisted.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hmac
+import json
+import os
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+import re
+from typing import Any, Mapping
+from urllib.parse import urlparse
+
+from aios_agent_task_protocol import TaskProtocolError, TaskStore
+
+
+MAX_BODY = 1024 * 1024
+TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{2,179}$")
+
+
+@dataclass(frozen=True, slots=True)
+class APIConfig:
+    db_path: Path
+    control_token_path: Path
+    host: str = "127.0.0.1"
+    port: int = 18940
+    token_pepper: str = ""
+
+    @classmethod
+    def from_env(cls) -> "APIConfig":
+        return cls(
+            db_path=Path(os.getenv(
+                "AIOS_AGENT_TASK_DB",
+                "/var/lib/aios-agent-task/state.sqlite3",
+            )),
+            control_token_path=Path(os.getenv(
+                "AIOS_AGENT_TASK_CONTROL_TOKEN_FILE",
+                "/run/credentials/aios-agent-task-api.service/control_token",
+            )),
+            host=os.getenv("AIOS_AGENT_TASK_HOST", "127.0.0.1"),
+            port=int(os.getenv("AIOS_AGENT_TASK_PORT", "18940")),
+            token_pepper=os.getenv("AIOS_AGENT_TASK_TOKEN_PEPPER", ""),
+        )
+
+
+class AgentTaskApplication:
+    def __init__(self, config: APIConfig) -> None:
+        self.config = config
+        self.store = TaskStore(
+            config.db_path,
+            token_pepper=config.token_pepper,
+        )
+
+    def _control_token(self) -> str:
+        path = self.config.control_token_path
+        if path.is_symlink() or not path.is_file():
+            raise TaskProtocolError("CONTROL_CREDENTIAL_UNAVAILABLE", 503)
+        value = path.read_text(encoding="utf-8").strip()
+        if len(value) < 32:
+            raise TaskProtocolError("CONTROL_CREDENTIAL_INVALID", 503)
+        return value
+
+    @staticmethod
+    def _bearer(headers: Mapping[str, str]) -> str:
+        value = str(headers.get("Authorization") or "")
+        if not value.startswith("Bearer "):
+            return ""
+        return value[7:].strip()
+
+    def authenticate_control(self, headers: Mapping[str, str]) -> None:
+        supplied = self._bearer(headers)
+        expected = self._control_token()
+        if not supplied or not hmac.compare_digest(supplied, expected):
+            raise TaskProtocolError("UNAUTHORIZED", 401)
+
+    def authenticate_agent(self, headers: Mapping[str, str]) -> dict[str, Any]:
+        return self.store.authenticate_agent(self._bearer(headers))
+
+    def principal(self, headers: Mapping[str, str]) -> tuple[str, dict[str, Any] | None]:
+        supplied = self._bearer(headers)
+        if not supplied:
+            raise TaskProtocolError("UNAUTHORIZED", 401)
+        try:
+            expected = self._control_token()
+        except TaskProtocolError:
+            expected = ""
+        if expected and hmac.compare_digest(supplied, expected):
+            return "control", None
+        return "agent", self.store.authenticate_agent(supplied)
+
+    def health(self) -> dict[str, Any]:
+        return {
+            "status": "ok",
+            "schema": "aios.agent-task.v1",
+            "task_states": [
+                "QUEUED", "CLAIMED", "RUNNING", "VERIFYING",
+                "SUCCEEDED", "FAILED", "EXPIRED", "CANCELLED",
+            ],
+            "lease_recovery": True,
+            "atomic_claim": True,
+            "idempotent_result_submission": True,
+            "server_side_verification_required": True,
+            "plaintext_credentials_persisted": False,
+        }
+
+    def register_agent(self, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        self.authenticate_control(headers)
+        return self.store.register_agent(
+            agent_id=str(body.get("agent_id") or ""),
+            agent_type=str(body.get("agent_type") or ""),
+            agent_version=str(body.get("agent_version") or ""),
+            capabilities=body.get("capabilities") or [],
+            metadata=body.get("metadata") if isinstance(body.get("metadata"), Mapping) else {},
+        )
+
+    def create_task(self, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        self.authenticate_control(headers)
+        return self.store.create_task(
+            task_id=str(body.get("task_id") or "") or None,
+            goal=str(body.get("goal") or ""),
+            instructions=str(body.get("instructions") or ""),
+            success_criteria=body.get("success_criteria"),
+            required_capabilities=body.get("required_capabilities") or [],
+            constraints=body.get("constraints") if isinstance(body.get("constraints"), Mapping) else {},
+            metadata=body.get("metadata") if isinstance(body.get("metadata"), Mapping) else {},
+            deadline=str(body.get("deadline") or "") or None,
+            priority=body.get("priority", 0),
+            max_attempts=body.get("max_attempts", 3),
+            idempotency_key=str(body.get("idempotency_key") or ""),
+        )
+
+    def poll(self, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        agent = self.authenticate_agent(headers)
+        tasks = self.store.poll_tasks(
+            agent_id=agent["agent_id"],
+            limit=int(body.get("limit", 20)),
+        )
+        return {"agent_id": agent["agent_id"], "tasks": tasks}
+
+    def claim(self, task_id: str, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        agent = self.authenticate_agent(headers)
+        return self.store.claim_task(
+            task_id=task_id,
+            agent_id=agent["agent_id"],
+            lease_seconds=int(body.get("lease_seconds", 300)),
+        )
+
+    def heartbeat(self, task_id: str, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        agent = self.authenticate_agent(headers)
+        return self.store.heartbeat(
+            task_id=task_id,
+            agent_id=agent["agent_id"],
+            lease_token=str(body.get("lease_token") or ""),
+            progress=body.get("progress") if isinstance(body.get("progress"), Mapping) else {},
+            lease_seconds=int(body.get("lease_seconds", 300)),
+        )
+
+    def result(self, task_id: str, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        agent = self.authenticate_agent(headers)
+        result = body.get("result")
+        if not isinstance(result, Mapping):
+            raise TaskProtocolError("RESULT_INVALID", 400)
+        return self.store.submit_result(
+            task_id=task_id,
+            agent_id=agent["agent_id"],
+            lease_token=str(body.get("lease_token") or ""),
+            idempotency_key=str(body.get("idempotency_key") or ""),
+            result=result,
+        )
+
+    def verify(self, task_id: str, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        self.authenticate_control(headers)
+        return self.store.verify_task(
+            task_id=task_id,
+            decision=str(body.get("decision") or ""),
+            verification=body.get("verification") if isinstance(body.get("verification"), Mapping) else {},
+        )
+
+    def cancel(self, task_id: str, headers: Mapping[str, str], body: Mapping[str, Any]) -> dict[str, Any]:
+        self.authenticate_control(headers)
+        return self.store.cancel_task(task_id=task_id, reason=str(body.get("reason") or ""))
+
+    def get_task(self, task_id: str, headers: Mapping[str, str]) -> dict[str, Any]:
+        kind, agent = self.principal(headers)
+        task = self.store.get_task(task_id)
+        if kind == "agent" and task.get("claimed_by") != agent["agent_id"]:
+            raise TaskProtocolError("FORBIDDEN", 403)
+        return task
+
+    def events(self, task_id: str, headers: Mapping[str, str]) -> dict[str, Any]:
+        self.authenticate_control(headers)
+        return {"task_id": task_id, "events": self.store.get_events(task_id)}
+
+
+class Handler(BaseHTTPRequestHandler):
+    app: AgentTaskApplication | None = None
+    server_version = "AIOSAgentTaskAPI/1"
+
+    def log_message(self, _format: str, *_args: Any) -> None:
+        return
+
+    def _headers(self) -> dict[str, str]:
+        return {key: value for key, value in self.headers.items()}
+
+    def _json(self, value: Any, status: int = 200) -> None:
+        payload = json.dumps(value, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _body(self) -> dict[str, Any]:
+        try:
+            size = int(self.headers.get("Content-Length", "0"))
+        except ValueError as exc:
+            raise TaskProtocolError("CONTENT_LENGTH_INVALID", 400) from exc
+        if size < 0 or size > MAX_BODY:
+            raise TaskProtocolError("REQUEST_TOO_LARGE", 413)
+        raw = self.rfile.read(size) if size else b"{}"
+        try:
+            value = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise TaskProtocolError("JSON_INVALID", 400) from exc
+        if not isinstance(value, dict):
+            raise TaskProtocolError("JSON_OBJECT_REQUIRED", 400)
+        return value
+
+    @staticmethod
+    def _task_route(path: str) -> tuple[str, str | None]:
+        match = re.fullmatch(
+            r"/v1/tasks/([A-Za-z0-9][A-Za-z0-9._:-]{2,179})(?:/(claim|heartbeat|result|verify|cancel|events))?",
+            path,
+        )
+        if match:
+            return match.group(1), match.group(2)
+        return "", None
+
+    def _run(self, callback) -> None:
+        try:
+            callback()
+        except TaskProtocolError as exc:
+            self._json({"error": exc.code}, exc.http_status)
+        except Exception as exc:
+            self._json({"error": "INTERNAL_ERROR", "detail": type(exc).__name__}, 500)
+
+    def do_GET(self) -> None:
+        def action() -> None:
+            if self.app is None:
+                raise TaskProtocolError("SERVICE_UNAVAILABLE", 503)
+            path = urlparse(self.path).path.rstrip("/") or "/"
+            if path == "/health":
+                self._json(self.app.health())
+                return
+            task_id, suffix = self._task_route(path)
+            if task_id and suffix is None:
+                self._json(self.app.get_task(task_id, self._headers()))
+                return
+            if task_id and suffix == "events":
+                self._json(self.app.events(task_id, self._headers()))
+                return
+            self._json({"error": "NOT_FOUND"}, 404)
+        self._run(action)
+
+    def do_POST(self) -> None:
+        def action() -> None:
+            if self.app is None:
+                raise TaskProtocolError("SERVICE_UNAVAILABLE", 503)
+            path = urlparse(self.path).path.rstrip("/") or "/"
+            body = self._body()
+            if path == "/v1/agents/register":
+                self._json(self.app.register_agent(self._headers(), body), 201)
+                return
+            if path == "/v1/tasks":
+                self._json(self.app.create_task(self._headers(), body), 201)
+                return
+            if path == "/v1/tasks/poll":
+                self._json(self.app.poll(self._headers(), body))
+                return
+            task_id, suffix = self._task_route(path)
+            if not task_id:
+                self._json({"error": "NOT_FOUND"}, 404)
+                return
+            if suffix == "claim":
+                self._json(self.app.claim(task_id, self._headers(), body))
+            elif suffix == "heartbeat":
+                self._json(self.app.heartbeat(task_id, self._headers(), body))
+            elif suffix == "result":
+                self._json(self.app.result(task_id, self._headers(), body))
+            elif suffix == "verify":
+                self._json(self.app.verify(task_id, self._headers(), body))
+            elif suffix == "cancel":
+                self._json(self.app.cancel(task_id, self._headers(), body))
+            else:
+                self._json({"error": "NOT_FOUND"}, 404)
+        self._run(action)
+
+
+def serve(config: APIConfig | None = None) -> None:
+    config = config or APIConfig.from_env()
+    application = AgentTaskApplication(config)
+    Handler.app = application
+    ThreadingHTTPServer((config.host, config.port), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    serve()

active-runtime/app/aios_agent_task_protocol.py

@@ -0,0 +1,829 @@
+#!/usr/bin/env python3
+"""Durable online task protocol for external AIOS agents.
+
+The store is deliberately independent from Git/Gitea mutation. It provides a
+small durable state machine for publishing work, atomic claim/lease ownership,
+heartbeat, idempotent result submission, explicit server-side verification,
+lease recovery, and audit events.
+
+No plaintext agent credential or task lease token is persisted.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+import hashlib
+import hmac
+import json
+from pathlib import Path
+import secrets
+import sqlite3
+from typing import Any, Callable, Iterable, Mapping
+import uuid
+
+from aios_capability_contract import has_capabilities
+
+
+TERMINAL_STATES = frozenset({"SUCCEEDED", "FAILED", "EXPIRED", "CANCELLED"})
+ACTIVE_LEASE_STATES = frozenset({"CLAIMED", "RUNNING"})
+TASK_STATES = frozenset({
+    "QUEUED", "CLAIMED", "RUNNING", "VERIFYING",
+    "SUCCEEDED", "FAILED", "EXPIRED", "CANCELLED",
+})
+VERIFY_DECISIONS = frozenset({"SUCCEEDED", "NEEDS_REWORK", "FAILED"})
+
+
+class TaskProtocolError(RuntimeError):
+    def __init__(self, code: str, http_status: int = 409) -> None:
+        super().__init__(code)
+        self.code = code
+        self.http_status = http_status
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    kind: str
+    identifier: str
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def iso(value: datetime) -> str:
+    return value.astimezone(timezone.utc).isoformat()
+
+
+def parse_time(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    parsed = datetime.fromisoformat(value)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def digest_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def _string_list(value: Iterable[object] | None, field: str, *, max_items: int = 128) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (str, bytes)) or not isinstance(value, Iterable):
+        raise TaskProtocolError(field.upper() + "_INVALID", 400)
+    result: list[str] = []
+    for item in value:
+        text = str(item).strip()
+        if not text or len(text) > 160:
+            raise TaskProtocolError(field.upper() + "_INVALID", 400)
+        result.append(text)
+        if len(result) > max_items:
+            raise TaskProtocolError(field.upper() + "_TOO_LARGE", 400)
+    return sorted(set(result))
+
+
+def _json_object(value: object | None, field: str, *, max_bytes: int = 128 * 1024) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise TaskProtocolError(field.upper() + "_INVALID", 400)
+    result = dict(value)
+    if len(canonical_json(result).encode("utf-8")) > max_bytes:
+        raise TaskProtocolError(field.upper() + "_TOO_LARGE", 413)
+    return result
+
+
+def _criteria(value: object | None) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, (str, bytes)) or not isinstance(value, list):
+        raise TaskProtocolError("SUCCESS_CRITERIA_INVALID", 400)
+    if len(value) > 128:
+        raise TaskProtocolError("SUCCESS_CRITERIA_TOO_LARGE", 413)
+    if len(canonical_json(value).encode("utf-8")) > 128 * 1024:
+        raise TaskProtocolError("SUCCESS_CRITERIA_TOO_LARGE", 413)
+    return list(value)
+
+
+class TaskStore:
+    """SQLite-backed durable task store.
+
+    SQLite BEGIN IMMEDIATE serializes claims so two agents cannot successfully
+    claim the same queued task. WAL mode allows concurrent readers.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        now: Callable[[], datetime] = utcnow,
+        token_pepper: str = "",
+    ) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.now = now
+        self.token_pepper = token_pepper
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.path, timeout=10, isolation_level=None)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA foreign_keys=ON")
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA synchronous=FULL")
+        connection.execute("PRAGMA busy_timeout=10000")
+        return connection
+
+    def _initialize(self) -> None:
+        with self._connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS agents (
+                    agent_id TEXT PRIMARY KEY,
+                    agent_type TEXT NOT NULL,
+                    agent_version TEXT NOT NULL,
+                    capabilities_json TEXT NOT NULL,
+                    metadata_json TEXT NOT NULL,
+                    token_hash TEXT NOT NULL UNIQUE,
+                    status TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    last_seen_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS tasks (
+                    task_id TEXT PRIMARY KEY,
+                    goal TEXT NOT NULL,
+                    instructions TEXT NOT NULL,
+                    success_criteria_json TEXT NOT NULL,
+                    required_capabilities_json TEXT NOT NULL,
+                    constraints_json TEXT NOT NULL,
+                    metadata_json TEXT NOT NULL,
+                    deadline TEXT,
+                    priority INTEGER NOT NULL,
+                    max_attempts INTEGER NOT NULL,
+                    attempt INTEGER NOT NULL DEFAULT 0,
+                    status TEXT NOT NULL,
+                    claimed_by TEXT,
+                    lease_token_hash TEXT,
+                    lease_expires_at TEXT,
+                    result_json TEXT,
+                    result_digest TEXT,
+                    result_idempotency_key TEXT,
+                    verification_json TEXT,
+                    revision INTEGER NOT NULL DEFAULT 1,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL,
+                    FOREIGN KEY(claimed_by) REFERENCES agents(agent_id)
+                );
+
+                CREATE TABLE IF NOT EXISTS idempotency (
+                    scope TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    payload_digest TEXT NOT NULL,
+                    response_json TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    PRIMARY KEY(scope, key)
+                );
+
+                CREATE TABLE IF NOT EXISTS events (
+                    event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    task_id TEXT,
+                    agent_id TEXT,
+                    event_type TEXT NOT NULL,
+                    payload_json TEXT NOT NULL,
+                    created_at TEXT NOT NULL
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_tasks_queue
+                ON tasks(status, priority DESC, created_at);
+
+                CREATE INDEX IF NOT EXISTS idx_tasks_lease
+                ON tasks(status, lease_expires_at);
+
+                CREATE INDEX IF NOT EXISTS idx_events_task
+                ON events(task_id, event_id);
+                """
+            )
+
+    def _token_hash(self, token: str) -> str:
+        return hashlib.sha256((self.token_pepper + "\0" + token).encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _row_task(row: sqlite3.Row, *, include_result: bool = True) -> dict[str, Any]:
+        value: dict[str, Any] = {
+            "task_id": row["task_id"],
+            "goal": row["goal"],
+            "instructions": row["instructions"],
+            "success_criteria": json.loads(row["success_criteria_json"]),
+            "required_capabilities": json.loads(row["required_capabilities_json"]),
+            "constraints": json.loads(row["constraints_json"]),
+            "metadata": json.loads(row["metadata_json"]),
+            "deadline": row["deadline"],
+            "priority": row["priority"],
+            "max_attempts": row["max_attempts"],
+            "attempt": row["attempt"],
+            "status": row["status"],
+            "claimed_by": row["claimed_by"],
+            "lease_expires_at": row["lease_expires_at"],
+            "revision": row["revision"],
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }
+        if include_result:
+            value["result"] = json.loads(row["result_json"]) if row["result_json"] else None
+            value["verification"] = (
+                json.loads(row["verification_json"]) if row["verification_json"] else None
+            )
+        return value
+
+    def _event(
+        self,
+        connection: sqlite3.Connection,
+        event_type: str,
+        *,
+        task_id: str | None = None,
+        agent_id: str | None = None,
+        payload: Mapping[str, Any] | None = None,
+    ) -> None:
+        connection.execute(
+            "INSERT INTO events(task_id,agent_id,event_type,payload_json,created_at)"
+            " VALUES(?,?,?,?,?)",
+            (task_id, agent_id, event_type, canonical_json(dict(payload or {})), iso(self.now())),
+        )
+
+    def register_agent(
+        self,
+        *,
+        agent_id: str,
+        agent_type: str,
+        agent_version: str,
+        capabilities: Iterable[object],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        agent_id = agent_id.strip()
+        agent_type = agent_type.strip()
+        agent_version = agent_version.strip()
+        if not agent_id or len(agent_id) > 160 or not agent_type or not agent_version:
+            raise TaskProtocolError("AGENT_IDENTITY_INVALID", 400)
+        caps = _string_list(capabilities, "capabilities")
+        meta = _json_object(metadata, "metadata")
+        token = "agt_" + secrets.token_urlsafe(32)
+        now = iso(self.now())
+        try:
+            with self._connect() as connection:
+                connection.execute("BEGIN IMMEDIATE")
+                connection.execute(
+                    "INSERT INTO agents(agent_id,agent_type,agent_version,capabilities_json,"
+                    "metadata_json,token_hash,status,created_at,last_seen_at)"
+                    " VALUES(?,?,?,?,?,?,?,?,?)",
+                    (
+                        agent_id,
+                        agent_type,
+                        agent_version,
+                        canonical_json(caps),
+                        canonical_json(meta),
+                        self._token_hash(token),
+                        "ACTIVE",
+                        now,
+                        now,
+                    ),
+                )
+                self._event(
+                    connection,
+                    "AGENT_REGISTERED",
+                    agent_id=agent_id,
+                    payload={"agent_type": agent_type, "agent_version": agent_version},
+                )
+                connection.commit()
+        except sqlite3.IntegrityError as exc:
+            raise TaskProtocolError("AGENT_ALREADY_EXISTS", 409) from exc
+        return {
+            "agent_id": agent_id,
+            "agent_type": agent_type,
+            "agent_version": agent_version,
+            "capabilities": caps,
+            "agent_token": token,
+            "credential_returned_once": True,
+        }
+
+    def authenticate_agent(self, token: str) -> dict[str, Any]:
+        if not token:
+            raise TaskProtocolError("UNAUTHORIZED", 401)
+        token_hash = self._token_hash(token)
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT * FROM agents WHERE token_hash=? AND status='ACTIVE'",
+                (token_hash,),
+            ).fetchone()
+            if row is None:
+                raise TaskProtocolError("UNAUTHORIZED", 401)
+            connection.execute(
+                "UPDATE agents SET last_seen_at=? WHERE agent_id=?",
+                (iso(self.now()), row["agent_id"]),
+            )
+            return {
+                "agent_id": row["agent_id"],
+                "agent_type": row["agent_type"],
+                "agent_version": row["agent_version"],
+                "capabilities": json.loads(row["capabilities_json"]),
+                "metadata": json.loads(row["metadata_json"]),
+            }
+
+    def _idempotent_lookup(
+        self,
+        connection: sqlite3.Connection,
+        *,
+        scope: str,
+        key: str,
+        payload_digest: str,
+    ) -> dict[str, Any] | None:
+        row = connection.execute(
+            "SELECT payload_digest,response_json FROM idempotency WHERE scope=? AND key=?",
+            (scope, key),
+        ).fetchone()
+        if row is None:
+            return None
+        if not hmac.compare_digest(row["payload_digest"], payload_digest):
+            raise TaskProtocolError("IDEMPOTENCY_CONFLICT", 409)
+        return json.loads(row["response_json"])
+
+    def _idempotent_store(
+        self,
+        connection: sqlite3.Connection,
+        *,
+        scope: str,
+        key: str,
+        payload_digest: str,
+        response: Mapping[str, Any],
+    ) -> None:
+        connection.execute(
+            "INSERT INTO idempotency(scope,key,payload_digest,response_json,created_at)"
+            " VALUES(?,?,?,?,?)",
+            (scope, key, payload_digest, canonical_json(dict(response)), iso(self.now())),
+        )
+
+    def create_task(
+        self,
+        *,
+        task_id: str | None,
+        goal: str,
+        instructions: str,
+        success_criteria: object | None,
+        required_capabilities: Iterable[object] | None = None,
+        constraints: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        deadline: str | None = None,
+        priority: int = 0,
+        max_attempts: int = 3,
+        idempotency_key: str,
+    ) -> dict[str, Any]:
+        task_id = (task_id or ("task-" + uuid.uuid4().hex)).strip()
+        goal = goal.strip()
+        instructions = instructions.strip()
+        idempotency_key = idempotency_key.strip()
+        if not task_id or len(task_id) > 180 or not goal or not instructions:
+            raise TaskProtocolError("TASK_BINDING_INVALID", 400)
+        if not idempotency_key or len(idempotency_key) > 160:
+            raise TaskProtocolError("IDEMPOTENCY_KEY_INVALID", 400)
+        if not isinstance(priority, int) or isinstance(priority, bool) or not -100 <= priority <= 100:
+            raise TaskProtocolError("PRIORITY_INVALID", 400)
+        if not isinstance(max_attempts, int) or isinstance(max_attempts, bool) or not 1 <= max_attempts <= 20:
+            raise TaskProtocolError("MAX_ATTEMPTS_INVALID", 400)
+        parsed_deadline = parse_time(deadline)
+        if parsed_deadline and parsed_deadline <= self.now():
+            raise TaskProtocolError("DEADLINE_INVALID", 400)
+        criteria = _criteria(success_criteria)
+        required = _string_list(required_capabilities, "required_capabilities")
+        constraints_value = _json_object(constraints, "constraints")
+        metadata_value = _json_object(metadata, "metadata")
+        payload = {
+            "task_id": task_id,
+            "goal": goal,
+            "instructions": instructions,
+            "success_criteria": criteria,
+            "required_capabilities": required,
+            "constraints": constraints_value,
+            "metadata": metadata_value,
+            "deadline": iso(parsed_deadline) if parsed_deadline else None,
+            "priority": priority,
+            "max_attempts": max_attempts,
+        }
+        payload_digest = digest_json(payload)
+        now = iso(self.now())
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            replay = self._idempotent_lookup(
+                connection,
+                scope="create_task",
+                key=idempotency_key,
+                payload_digest=payload_digest,
+            )
+            if replay is not None:
+                connection.commit()
+                return {**replay, "idempotent": True}
+            try:
+                connection.execute(
+                    "INSERT INTO tasks(task_id,goal,instructions,success_criteria_json,"
+                    "required_capabilities_json,constraints_json,metadata_json,deadline,priority,"
+                    "max_attempts,attempt,status,revision,created_at,updated_at)"
+                    " VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        task_id,
+                        goal,
+                        instructions,
+                        canonical_json(criteria),
+                        canonical_json(required),
+                        canonical_json(constraints_value),
+                        canonical_json(metadata_value),
+                        payload["deadline"],
+                        priority,
+                        max_attempts,
+                        0,
+                        "QUEUED",
+                        1,
+                        now,
+                        now,
+                    ),
+                )
+            except sqlite3.IntegrityError as exc:
+                raise TaskProtocolError("TASK_ID_CONFLICT", 409) from exc
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            result = self._row_task(row)
+            self._idempotent_store(
+                connection,
+                scope="create_task",
+                key=idempotency_key,
+                payload_digest=payload_digest,
+                response=result,
+            )
+            self._event(connection, "TASK_CREATED", task_id=task_id, payload={"priority": priority})
+            connection.commit()
+            return result
+
+    def _expire_locked(self, connection: sqlite3.Connection) -> None:
+        now_dt = self.now()
+        now = iso(now_dt)
+        rows = connection.execute(
+            "SELECT * FROM tasks WHERE status IN ('QUEUED','CLAIMED','RUNNING')"
+        ).fetchall()
+        for row in rows:
+            deadline = parse_time(row["deadline"])
+            if deadline is not None and deadline <= now_dt:
+                connection.execute(
+                    "UPDATE tasks SET status='EXPIRED',lease_token_hash=NULL,"
+                    "lease_expires_at=NULL,revision=revision+1,updated_at=? WHERE task_id=?",
+                    (now, row["task_id"]),
+                )
+                self._event(connection, "TASK_EXPIRED", task_id=row["task_id"])
+                continue
+            if row["status"] in ACTIVE_LEASE_STATES:
+                lease_expires = parse_time(row["lease_expires_at"])
+                if lease_expires is not None and lease_expires <= now_dt:
+                    if row["attempt"] >= row["max_attempts"]:
+                        next_state = "FAILED"
+                    else:
+                        next_state = "QUEUED"
+                    if next_state == "FAILED":
+                        connection.execute(
+                            "UPDATE tasks SET status=?,lease_token_hash=NULL,"
+                            "lease_expires_at=NULL,revision=revision+1,updated_at=? WHERE task_id=?",
+                            (next_state, now, row["task_id"]),
+                        )
+                    else:
+                        connection.execute(
+                            "UPDATE tasks SET status=?,claimed_by=NULL,lease_token_hash=NULL,"
+                            "lease_expires_at=NULL,revision=revision+1,updated_at=? WHERE task_id=?",
+                            (next_state, now, row["task_id"]),
+                        )
+                    self._event(
+                        connection,
+                        "LEASE_EXPIRED",
+                        task_id=row["task_id"],
+                        agent_id=row["claimed_by"],
+                        payload={"next_state": next_state, "attempt": row["attempt"]},
+                    )
+
+    def expire_leases(self) -> int:
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            before = connection.total_changes
+            self._expire_locked(connection)
+            changed = connection.total_changes - before
+            connection.commit()
+            return changed
+
+    def poll_tasks(self, *, agent_id: str, limit: int = 20) -> list[dict[str, Any]]:
+        if not 1 <= int(limit) <= 100:
+            raise TaskProtocolError("LIMIT_INVALID", 400)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            self._expire_locked(connection)
+            agent = connection.execute(
+                "SELECT capabilities_json FROM agents WHERE agent_id=? AND status='ACTIVE'",
+                (agent_id,),
+            ).fetchone()
+            if agent is None:
+                raise TaskProtocolError("AGENT_NOT_FOUND", 404)
+            capabilities = json.loads(agent["capabilities_json"])
+            rows = connection.execute(
+                "SELECT * FROM tasks WHERE status='QUEUED' ORDER BY priority DESC,created_at ASC"
+            ).fetchall()
+            result = []
+            for row in rows:
+                required = json.loads(row["required_capabilities_json"])
+                if has_capabilities(capabilities, required):
+                    result.append(self._row_task(row, include_result=False))
+                    if len(result) >= int(limit):
+                        break
+            connection.commit()
+            return result
+
+    def _agent_capabilities(self, connection: sqlite3.Connection, agent_id: str) -> set[str]:
+        row = connection.execute(
+            "SELECT capabilities_json FROM agents WHERE agent_id=? AND status='ACTIVE'",
+            (agent_id,),
+        ).fetchone()
+        if row is None:
+            raise TaskProtocolError("AGENT_NOT_FOUND", 404)
+        return set(json.loads(row["capabilities_json"]))
+
+    def claim_task(
+        self,
+        *,
+        task_id: str,
+        agent_id: str,
+        lease_seconds: int = 300,
+    ) -> dict[str, Any]:
+        if not isinstance(lease_seconds, int) or isinstance(lease_seconds, bool) or not 30 <= lease_seconds <= 3600:
+            raise TaskProtocolError("LEASE_SECONDS_INVALID", 400)
+        lease_token = "lease_" + secrets.token_urlsafe(32)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            self._expire_locked(connection)
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskProtocolError("TASK_NOT_FOUND", 404)
+            if row["status"] != "QUEUED":
+                raise TaskProtocolError("TASK_NOT_CLAIMABLE", 409)
+            capabilities = self._agent_capabilities(connection, agent_id)
+            required = json.loads(row["required_capabilities_json"])
+            if not has_capabilities(capabilities, required):
+                raise TaskProtocolError("AGENT_CAPABILITY_MISMATCH", 403)
+            attempt = int(row["attempt"]) + 1
+            if attempt > int(row["max_attempts"]):
+                raise TaskProtocolError("TASK_ATTEMPTS_EXHAUSTED", 409)
+            expires = self.now() + timedelta(seconds=lease_seconds)
+            now = iso(self.now())
+            updated = connection.execute(
+                "UPDATE tasks SET status='CLAIMED',claimed_by=?,lease_token_hash=?,"
+                "lease_expires_at=?,attempt=?,revision=revision+1,updated_at=? "
+                "WHERE task_id=? AND status='QUEUED'",
+                (
+                    agent_id,
+                    self._token_hash(lease_token),
+                    iso(expires),
+                    attempt,
+                    now,
+                    task_id,
+                ),
+            )
+            if updated.rowcount != 1:
+                raise TaskProtocolError("TASK_CLAIM_CONFLICT", 409)
+            self._event(
+                connection,
+                "TASK_CLAIMED",
+                task_id=task_id,
+                agent_id=agent_id,
+                payload={"attempt": attempt, "lease_expires_at": iso(expires)},
+            )
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            connection.commit()
+            return {
+                **self._row_task(row, include_result=False),
+                "lease_token": lease_token,
+                "lease_token_returned_once": True,
+            }
+
+    def _validate_lease(
+        self,
+        connection: sqlite3.Connection,
+        *,
+        task_id: str,
+        agent_id: str,
+        lease_token: str,
+        allowed_states: frozenset[str] = ACTIVE_LEASE_STATES,
+    ) -> sqlite3.Row:
+        self._expire_locked(connection)
+        row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+        if row is None:
+            raise TaskProtocolError("TASK_NOT_FOUND", 404)
+        if row["status"] not in allowed_states:
+            raise TaskProtocolError("TASK_LEASE_NOT_ACTIVE", 409)
+        if row["claimed_by"] != agent_id:
+            raise TaskProtocolError("TASK_LEASE_OWNER_MISMATCH", 403)
+        if not row["lease_token_hash"] or not hmac.compare_digest(
+            row["lease_token_hash"], self._token_hash(lease_token)
+        ):
+            raise TaskProtocolError("TASK_LEASE_TOKEN_INVALID", 403)
+        expires = parse_time(row["lease_expires_at"])
+        if expires is None or expires <= self.now():
+            raise TaskProtocolError("TASK_LEASE_EXPIRED", 409)
+        return row
+
+    def heartbeat(
+        self,
+        *,
+        task_id: str,
+        agent_id: str,
+        lease_token: str,
+        progress: Mapping[str, Any] | None = None,
+        lease_seconds: int = 300,
+    ) -> dict[str, Any]:
+        if not 30 <= int(lease_seconds) <= 3600:
+            raise TaskProtocolError("LEASE_SECONDS_INVALID", 400)
+        progress_value = _json_object(progress, "progress", max_bytes=64 * 1024)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            self._validate_lease(
+                connection,
+                task_id=task_id,
+                agent_id=agent_id,
+                lease_token=lease_token,
+            )
+            expires = self.now() + timedelta(seconds=int(lease_seconds))
+            now = iso(self.now())
+            connection.execute(
+                "UPDATE tasks SET status='RUNNING',lease_expires_at=?,revision=revision+1,"
+                "updated_at=? WHERE task_id=?",
+                (iso(expires), now, task_id),
+            )
+            self._event(
+                connection,
+                "TASK_HEARTBEAT",
+                task_id=task_id,
+                agent_id=agent_id,
+                payload={"progress": progress_value, "lease_expires_at": iso(expires)},
+            )
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            connection.commit()
+            return self._row_task(row, include_result=False)
+
+    def submit_result(
+        self,
+        *,
+        task_id: str,
+        agent_id: str,
+        lease_token: str,
+        idempotency_key: str,
+        result: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        idempotency_key = idempotency_key.strip()
+        if not idempotency_key or len(idempotency_key) > 160:
+            raise TaskProtocolError("IDEMPOTENCY_KEY_INVALID", 400)
+        result_value = _json_object(result, "result", max_bytes=1024 * 1024)
+        result_digest = digest_json(result_value)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskProtocolError("TASK_NOT_FOUND", 404)
+            if row["result_idempotency_key"] == idempotency_key:
+                if not row["result_digest"] or not hmac.compare_digest(row["result_digest"], result_digest):
+                    raise TaskProtocolError("IDEMPOTENCY_CONFLICT", 409)
+                connection.commit()
+                return {**self._row_task(row), "idempotent": True}
+            self._validate_lease(
+                connection,
+                task_id=task_id,
+                agent_id=agent_id,
+                lease_token=lease_token,
+            )
+            now = iso(self.now())
+            connection.execute(
+                "UPDATE tasks SET status='VERIFYING',result_json=?,result_digest=?,"
+                "result_idempotency_key=?,lease_token_hash=NULL,lease_expires_at=NULL,"
+                "revision=revision+1,updated_at=? WHERE task_id=?",
+                (
+                    canonical_json(result_value),
+                    result_digest,
+                    idempotency_key,
+                    now,
+                    task_id,
+                ),
+            )
+            self._event(
+                connection,
+                "RESULT_SUBMITTED",
+                task_id=task_id,
+                agent_id=agent_id,
+                payload={"result_digest": result_digest, "idempotency_key": idempotency_key},
+            )
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            connection.commit()
+            return self._row_task(row)
+
+    def verify_task(
+        self,
+        *,
+        task_id: str,
+        decision: str,
+        verification: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        decision = decision.strip().upper()
+        if decision not in VERIFY_DECISIONS:
+            raise TaskProtocolError("VERIFICATION_DECISION_INVALID", 400)
+        verification_value = _json_object(verification, "verification")
+        verification_value = {"decision": decision, **verification_value}
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskProtocolError("TASK_NOT_FOUND", 404)
+            if row["status"] != "VERIFYING":
+                raise TaskProtocolError("TASK_NOT_VERIFYING", 409)
+            if decision == "SUCCEEDED":
+                next_state = "SUCCEEDED"
+            elif decision == "FAILED":
+                next_state = "FAILED"
+            elif int(row["attempt"]) >= int(row["max_attempts"]):
+                next_state = "FAILED"
+                verification_value["reason"] = verification_value.get(
+                    "reason", "MAX_ATTEMPTS_EXHAUSTED"
+                )
+            else:
+                next_state = "QUEUED"
+            now = iso(self.now())
+            if next_state in {"SUCCEEDED", "FAILED"}:
+                connection.execute(
+                    "UPDATE tasks SET status=?,lease_token_hash=NULL,"
+                    "lease_expires_at=NULL,verification_json=?,revision=revision+1,updated_at=? "
+                    "WHERE task_id=?",
+                    (next_state, canonical_json(verification_value), now, task_id),
+                )
+            else:
+                connection.execute(
+                    "UPDATE tasks SET status=?,claimed_by=NULL,lease_token_hash=NULL,"
+                    "lease_expires_at=NULL,verification_json=?,revision=revision+1,updated_at=? "
+                    "WHERE task_id=?",
+                    (next_state, canonical_json(verification_value), now, task_id),
+                )
+            self._event(
+                connection,
+                "TASK_VERIFIED",
+                task_id=task_id,
+                agent_id=row["claimed_by"],
+                payload={"decision": decision, "next_state": next_state},
+            )
+            updated = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            connection.commit()
+            return self._row_task(updated)
+
+    def cancel_task(self, *, task_id: str, reason: str = "") -> dict[str, Any]:
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskProtocolError("TASK_NOT_FOUND", 404)
+            if row["status"] in TERMINAL_STATES:
+                connection.commit()
+                return self._row_task(row)
+            connection.execute(
+                "UPDATE tasks SET status='CANCELLED',lease_token_hash=NULL,"
+                "lease_expires_at=NULL,revision=revision+1,updated_at=? WHERE task_id=?",
+                (iso(self.now()), task_id),
+            )
+            self._event(connection, "TASK_CANCELLED", task_id=task_id, payload={"reason": reason})
+            updated = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            connection.commit()
+            return self._row_task(updated)
+
+    def get_task(self, task_id: str) -> dict[str, Any]:
+        self.expire_leases()
+        with self._connect() as connection:
+            row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskProtocolError("TASK_NOT_FOUND", 404)
+            return self._row_task(row)
+
+    def get_events(self, task_id: str, *, limit: int = 200) -> list[dict[str, Any]]:
+        with self._connect() as connection:
+            rows = connection.execute(
+                "SELECT * FROM events WHERE task_id=? ORDER BY event_id DESC LIMIT ?",
+                (task_id, max(1, min(int(limit), 1000))),
+            ).fetchall()
+            return [
+                {
+                    "event_id": row["event_id"],
+                    "task_id": row["task_id"],
+                    "agent_id": row["agent_id"],
+                    "event_type": row["event_type"],
+                    "payload": json.loads(row["payload_json"]),
+                    "created_at": row["created_at"],
+                }
+                for row in reversed(rows)
+            ]

active-runtime/app/aios_branch_binding.py

@@ -0,0 +1,20 @@
+"""Shared exact branch-name validation for governed Git operations."""
+
+from __future__ import annotations
+
+import re
+
+
+# Keep the existing governed branch envelope. Validation rejects invalid input;
+# it never shortens or normalizes a caller's branch string.
+BRANCH_RE = re.compile(r"^agent/[A-Za-z0-9][A-Za-z0-9._/-]{2,179}$")
+
+
+def is_valid_governed_branch(value: object) -> bool:
+    return isinstance(value, str) and BRANCH_RE.fullmatch(value) is not None
+
+
+def require_exact_governed_branch(value: object, *, field: str = "target_branch") -> str:
+    if not is_valid_governed_branch(value):
+        raise ValueError(f"{field}_invalid")
+    return value

active-runtime/app/aios_capability_contract.py

@@ -0,0 +1,159 @@
+"""Canonical fail-closed capability semantics for task eligibility."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+_TASK_ALIASES: dict[str, frozenset[str]] = {
+    "repository_read": frozenset({"repo.read"}),
+    "git.read": frozenset({"repo.read"}),
+    "repo.read": frozenset({"repo.read"}),
+    "test_execution": frozenset({"test.execute"}),
+    "git.test": frozenset({"test.execute"}),
+    "test.execute": frozenset({"test.execute"}),
+    "governed_git_write": frozenset({"governed.git.write.branch", "governed.git.write.file"}),
+    "governed.git.write": frozenset({"governed.git.write.branch", "governed.git.write.file"}),
+    "governed.write.branch": frozenset({"governed.git.write.branch"}),
+    "governed.write.file": frozenset({"governed.git.write.file"}),
+    "shell": frozenset({"runtime.shell"}),
+    "git": frozenset({"runtime.git"}),
+    "python": frozenset({"runtime.python"}),
+    "code.read": frozenset({"legacy.code.read"}),
+    "code.review": frozenset({"legacy.code.review"}),
+    "code.write": frozenset({"legacy.code.write"}),
+    "code.write.patch": frozenset({"legacy.code.write.patch"}),
+    "test.python": frozenset({"legacy.test.python"}),
+    "test.shell.allowlisted": frozenset({"legacy.test.shell.allowlisted"}),
+    "git.commit": frozenset({"legacy.git.commit"}),
+    "git.diff.read": frozenset({"legacy.git.diff.read"}),
+    "git.force_push": frozenset({"legacy.git.force_push"}),
+    "deploy.production": frozenset({"legacy.deploy.production"}),
+    "secret.transform": frozenset({"legacy.secret.transform"}),
+    "secure_file_transformer": frozenset({"legacy.secure_file_transformer"}),
+    "runtime.shadow": frozenset({"legacy.runtime.shadow"}),
+    "review.security": frozenset({"legacy.review.security"}),
+    "review.api-contract": frozenset({"legacy.review.api-contract"}),
+    "gpu.train": frozenset({"legacy.gpu.train"}),
+}
+
+_WORKER_ALIASES: dict[str, frozenset[str]] = {
+    "git.read": frozenset({"repo.read"}),
+    "repo.read": frozenset({"repo.read"}),
+    "repository_read": frozenset({"repo.read"}),
+    "git.test": frozenset({"test.execute"}),
+    "test.execute": frozenset({"test.execute"}),
+    "test_execution": frozenset({"test.execute"}),
+    "governed.write.branch": frozenset({"governed.git.write.branch"}),
+    "governed.git.write.branch": frozenset({"governed.git.write.branch"}),
+    "governed.write.file": frozenset({"governed.git.write.file"}),
+    "governed.git.write.file": frozenset({"governed.git.write.file"}),
+    "shell": frozenset({"runtime.shell"}),
+    "git": frozenset({"runtime.git"}),
+    "python": frozenset({"runtime.python"}),
+    "code.read": frozenset({"legacy.code.read"}),
+    "code.review": frozenset({"legacy.code.review"}),
+    "code.write": frozenset({"legacy.code.write"}),
+    "code.write.patch": frozenset({"legacy.code.write.patch"}),
+    "test.python": frozenset({"legacy.test.python"}),
+    "test.shell.allowlisted": frozenset({"legacy.test.shell.allowlisted"}),
+    "git.commit": frozenset({"legacy.git.commit"}),
+    "git.diff.read": frozenset({"legacy.git.diff.read"}),
+    "git.force_push": frozenset({"legacy.git.force_push"}),
+    "deploy.production": frozenset({"legacy.deploy.production"}),
+    "secret.transform": frozenset({"legacy.secret.transform"}),
+    "secure_file_transformer": frozenset({"legacy.secure_file_transformer"}),
+    "runtime.shadow": frozenset({"legacy.runtime.shadow"}),
+    "review.security": frozenset({"legacy.review.security"}),
+    "review.api-contract": frozenset({"legacy.review.api-contract"}),
+    "gpu.train": frozenset({"legacy.gpu.train"}),
+}
+
+_UNKNOWN_PREFIX = "exact:"
+
+
+def _clean(value: object) -> str:
+    if not isinstance(value, str):
+        raise ValueError("capability must be a string")
+    text = value.strip().lower()
+    if not text:
+        raise ValueError("capability must not be empty")
+    return text
+
+
+def normalize_required_capabilities(values: Iterable[object]) -> frozenset[str]:
+    """Map task-facing names to one semantic vocabulary.
+
+    Unknown names remain explicit exact requirements. They are never treated
+    as wildcards or granted by a failed normalization.
+    """
+
+    result: set[str] = set()
+    for value in values:
+        text = _clean(value)
+        if "*" in text:
+            result.add(_UNKNOWN_PREFIX + text)
+        else:
+            result.update(_TASK_ALIASES.get(text, frozenset({_UNKNOWN_PREFIX + text})))
+    return frozenset(result)
+
+
+def normalize_worker_capabilities(values: Iterable[object]) -> frozenset[str]:
+    """Map registered worker names to effective semantic capabilities."""
+
+    result: set[str] = set()
+    for value in values:
+        text = _clean(value)
+        if "*" in text:
+            continue
+        mapped = _WORKER_ALIASES.get(text)
+        if mapped is not None:
+            result.update(mapped)
+    if {
+        "governed.git.write.branch",
+        "governed.git.write.file",
+    }.issubset(result):
+        result.add("governed.git.write")
+    return frozenset(result)
+
+
+def has_capabilities(
+    worker_capabilities: Iterable[object],
+    required_capabilities: Iterable[object],
+) -> bool:
+    """Return the single eligibility decision used by poll and claim."""
+
+    required = normalize_required_capabilities(required_capabilities)
+    effective = normalize_worker_capabilities(worker_capabilities)
+    if any(value.startswith(_UNKNOWN_PREFIX) for value in required):
+        return False
+    return required.issubset(effective)
+
+
+def required_capabilities_subset(
+    granted_requirements: Iterable[object],
+    required_requirements: Iterable[object],
+) -> bool:
+    """Check semantic capability containment for delegation constraints."""
+    granted = normalize_required_capabilities(granted_requirements)
+    required = normalize_required_capabilities(required_requirements)
+    if any(value.startswith(_UNKNOWN_PREFIX) for value in granted | required):
+        return False
+    return required.issubset(granted)
+
+
+def normalized_capability_matrix(
+    worker_capabilities: Iterable[object],
+    required_capabilities: Iterable[object],
+) -> dict[str, object]:
+    """Expose non-secret decision evidence for tests and diagnostics."""
+
+    worker_values = tuple(worker_capabilities)
+    required_values = tuple(required_capabilities)
+    worker = normalize_worker_capabilities(worker_values)
+    required = normalize_required_capabilities(required_values)
+    return {
+        "worker_effective": sorted(worker),
+        "task_required": sorted(required),
+        "eligible": has_capabilities(worker_values, required_values),
+    }

active-runtime/app/aios_chatgpt_bridge_v2_server.py

@@ -13,6 +13,7 @@ import sqlite3
 from typing import Any, Mapping
 
 from aios_authority_git_executor import AuthorityGitExecutor
+from aios_branch_binding import require_exact_governed_branch
 from aios_chatgpt_bridge_v2 import BridgeV2Adapter, BridgeV2Error, OPERATION_REQUIRED_FIELDS
 from aios_continuation_executor import AuthorityGitAdapter, ContinuationCommit, ContinuationExecutor, ContinuationPermissions, ContinuationRuntimeBinding, DetachedGitWorkspace, GiteaContinuationRemote, ServerSideCredentialProjection
 from aios_continuation_lease import WriterLeaseRequestV2
@@ -114,8 +115,13 @@ class GovernedRuntime:
     def _runtime(self, request: Mapping[str, Any]) -> tuple[Any, GitOpsJobController, ContinuationExecutor]:
         key = (str(request["task_id"]), int(request["generation"]))
         if key in self.runtimes: return self.runtimes[key]
-        lease = WriterLeaseRequestV2(task_id=str(request["task_id"]), repository=str(request["repository"]), branch_mode=str(request.get("branch_mode", "CONTINUE_EXISTING")), base_oid=str(request["base_oid"]), expected_branch_oid=str(request["expected_branch_oid"]), target_branch=str(request["target_branch"]), generation=int(request["generation"]), lease_seconds=int(request.get("lease_seconds", 900)))
+        requested_target_branch = request.get("target_branch")
+        if not isinstance(requested_target_branch, str):
+            raise RuntimeError("LEASE_BINDING_CONFLICT")
+        lease = WriterLeaseRequestV2(task_id=str(request["task_id"]), repository=str(request["repository"]), branch_mode=str(request.get("branch_mode", "CONTINUE_EXISTING")), base_oid=str(request["base_oid"]), expected_branch_oid=str(request["expected_branch_oid"]), target_branch=requested_target_branch, generation=int(request["generation"]), lease_seconds=int(request.get("lease_seconds", 900)))
         lease.validate(AuthorityGitAdapter(self.authority))
+        if lease.target_branch != requested_target_branch:
+            raise RuntimeError("LEASE_BINDING_CONFLICT")
         worktree_path = self.config.state_root / "worktrees" / _safe(lease.task_id)
         if worktree_path.exists():
             workspace = DetachedGitWorkspace(worktree_path)
@@ -133,6 +139,8 @@ class GovernedRuntime:
     def acquire_lease(self, request: Mapping[str, Any]) -> dict[str, Any]:
         binding, _, _ = self._runtime(request)
         req = binding.request
+        if request.get("target_branch") != req.target_branch:
+            raise RuntimeError("LEASE_BINDING_CONFLICT")
         return {"schema": WriterLeaseRequestV2.schema, "task_id": req.task_id, "repository": req.repository, "branch_mode": req.branch_mode, "base_oid": req.base_oid, "expected_branch_oid": req.expected_branch_oid, "target_branch": req.target_branch, "generation": req.generation, "lease_seconds": req.lease_seconds, "create_target_branch": req.branch_mode == "CREATE_NEW", "worktree_mode": "detached_at_base_oid" if req.branch_mode == "CREATE_NEW" else "detached_at_expected_head", "cas_ref_update_required": True}
 
     @staticmethod
@@ -145,7 +153,12 @@ class GovernedRuntime:
         runtime = self.runtimes.get((str(request["task_id"]), int(request["generation"])))
         if runtime is None: raise RuntimeError("LEASE_NOT_FOUND")
         binding, _, executor = runtime
-        if request["target_branch"] != binding.request.target_branch or request["expected_branch_oid"] != binding.request.expected_branch_oid: raise RuntimeError("LEASE_BINDING_CONFLICT")
+        if (
+            request["repository"] != binding.request.repository
+            or request["target_branch"] != binding.request.target_branch
+            or request["expected_branch_oid"] != binding.request.expected_branch_oid
+        ):
+            raise RuntimeError("LEASE_BINDING_CONFLICT")
         commit = ContinuationCommit(idempotency_key=str(request["idempotency_key"]), files=self._files(request), message=str(request["message"]))
         executor.workspace.materialize_files(commit.files)
         return executor.execute(binding, commit)
@@ -187,7 +200,16 @@ class GovernedRuntime:
         task_id = str(binding.get("task_id") or binding.get("campaign_id") or "").strip()
         repository = str(binding.get("repository") or "").strip()
         operation = str(binding.get("operation") or row.get("operation") or "").strip()
-        branch = str(binding.get("target_branch") or binding.get("branch") or row.get("branch") or "").strip()
+        branch_values = [
+            value for value in (binding.get("branch"), binding.get("target_branch"), row.get("branch"))
+            if value is not None
+        ]
+        if not branch_values or any(not isinstance(value, str) or value != branch_values[0] for value in branch_values):
+            raise RuntimeError("TARGET_BRANCH_BINDING_CONFLICT")
+        try:
+            branch = require_exact_governed_branch(branch_values[0])
+        except ValueError as exc:
+            raise RuntimeError("DURABLE_BINDING_INVALID") from exc
         expected = str(binding.get("expected_branch_oid") or row.get("expected_branch_oid") or "").strip()
         base = binding.get("base_oid") or binding.get("lineage_anchor_oid")
         if not base:

active-runtime/app/aios_continuation_executor.py

@@ -444,6 +444,7 @@ class ContinuationExecutor:
             "repository": request.repository,
             "operation": "CONTINUATION_COMMIT_FILES",
             "branch": request.target_branch,
+            "target_branch": request.target_branch,
             "expected_branch_oid": request.expected_branch_oid,
             "base_oid": request.base_oid,
             "branch_mode": request.branch_mode,

active-runtime/app/aios_continuation_lease.py

@@ -12,6 +12,8 @@ from datetime import datetime, timedelta, timezone
 import re
 from typing import Protocol
 
+from aios_branch_binding import BRANCH_RE
+
 
 OID_RE = re.compile(r"^[0-9a-f]{40}$")
 TARGET_BRANCH = "agent/autonomous-release-campaign-v1-20260807"
@@ -60,6 +62,8 @@ class WriterLeaseRequestV2:
             raise ContinuationError("branch_mode_invalid")
         _oid(self.base_oid, "base_oid")
         _oid(self.expected_branch_oid, "expected_branch_oid")
+        if not isinstance(self.target_branch, str) or BRANCH_RE.fullmatch(self.target_branch) is None:
+            raise ContinuationError("target_branch_invalid")
         if self.target_branch in {"main", "master"} or self.target_branch.startswith(("refs/", "tags/")):
             raise ContinuationError("protected_branch_rejected")
         if not isinstance(self.generation, int) or isinstance(self.generation, bool) or self.generation < 1:

active-runtime/app/aios_gitops_job_controller.py

@@ -18,6 +18,8 @@ import tempfile
 from datetime import datetime, timezone
 from typing import Any, Callable, Mapping
 
+from aios_branch_binding import is_valid_governed_branch
+
 
 class JobError(RuntimeError):
     pass
@@ -242,8 +244,26 @@ class JobStore:
             raise ServiceUnavailable("JOB_DB_UNAVAILABLE") from exc
         if row is None:
             raise JobError("JOB_NOT_FOUND")
+        self._validate_persisted_binding(row)
         return dict(row)
 
+    @staticmethod
+    def _validate_persisted_binding(row: Mapping[str, Any]) -> None:
+        try:
+            raw = json.loads(str(row["request_json"]))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise JobError("DURABLE_BINDING_INVALID") from exc
+        binding = raw.get("binding", raw)
+        if not isinstance(binding, Mapping):
+            raise JobError("DURABLE_BINDING_INVALID")
+        canonical_branch = row["branch"]
+        if not is_valid_governed_branch(canonical_branch):
+            raise JobError("DURABLE_BINDING_INVALID")
+        for field in ("branch", "target_branch"):
+            value = binding.get(field)
+            if value is not None and (not isinstance(value, str) or value != canonical_branch):
+                raise JobError("TARGET_BRANCH_BINDING_CONFLICT")
+
     def _receipt(self, row: Mapping[str, Any], *, duplicate: bool) -> JobReceipt:
         state = JobState(row["state"])
         if state == JobState.COMPLETED:
@@ -276,6 +296,11 @@ class GitOpsJobController:
             raise JobError("PAYLOAD_DIGEST_INVALID")
         if request["branch"] in {"main", "master"} or request["branch"].startswith(("refs/", "tags/")):
             raise JobError("PROTECTED_BRANCH_REJECTED")
+        target_branch = request.get("target_branch")
+        if target_branch is not None and (
+            not isinstance(target_branch, str) or target_branch != request["branch"]
+        ):
+            raise JobError("TARGET_BRANCH_BINDING_CONFLICT")
         binding = {field: str(request[field]) for field in fields}
         # Operation-specific, non-secret binding inputs must survive the
         # durable round trip and participate in idempotency. Arbitrary request
@@ -302,7 +327,7 @@ class GitOpsJobController:
                 continue
             if isinstance(value, bool) or not isinstance(value, (str, int)):
                 raise JobError("JOB_BINDING_OPTION_INVALID")
-            text = str(value).strip()
+            text = str(value) if field == "target_branch" else str(value).strip()
             if not text or len(text) > 512:
                 raise JobError("JOB_BINDING_OPTION_INVALID")
             binding[field] = text

active-runtime/app/aios_governed_task_bootstrap.py

@@ -78,7 +78,7 @@ class GovernedTaskBootstrap:
             if generation < 1: raise BootstrapError("GENERATION_INVALID")
         payload = json.dumps(values, sort_keys=True, separators=(",", ":")).encode()
         _, controller = self._store(values["task_id"])
-        receipt = controller.submit({"idempotency_key": values["idempotency_key"], "campaign_id": values["task_id"], "task_id": values["task_id"], "repository": values["repository"], "operation": "GOVERNED_TASK_CREATE", "branch": values["target_branch"], "expected_branch_oid": expected, "payload_digest": hashlib.sha256(payload).hexdigest(), "lineage_anchor_oid": values["base_oid"]}, payload=payload)
+        receipt = controller.submit({"idempotency_key": values["idempotency_key"], "campaign_id": values["task_id"], "task_id": values["task_id"], "repository": values["repository"], "operation": "GOVERNED_TASK_CREATE", "branch": values["target_branch"], "target_branch": values["target_branch"], "expected_branch_oid": expected, "payload_digest": hashlib.sha256(payload).hexdigest(), "lineage_anchor_oid": values["base_oid"]}, payload=payload)
         binding = GovernedTaskBinding(**values, expected_branch_oid=expected, branch_mode=mode, generation=generation, job_id=receipt.job_id)
         self._write(binding)
         return binding.response()

active-runtime/app/task_plane/capabilities.py

@@ -1,36 +1,25 @@
-"""Capability matcher helpers."""
+"""Compatibility facade for the canonical capability contract."""
 
 from __future__ import annotations
 
-from fnmatch import fnmatch
-
-
-def _normalize_capability(capability: str) -> str:
-    return capability.strip().lower()
+from aios_capability_contract import (
+    has_capabilities as _has_capabilities,
+    normalize_worker_capabilities,
+    required_capabilities_subset as _required_capabilities_subset,
+)
 
 
 def capability_matches(granted: str, required: str) -> bool:
-    granted = _normalize_capability(granted)
-    required = _normalize_capability(required)
-    if granted == required:
-        return True
-    # A granted wildcard such as "test.*" should match required "test.unit"
-    if "*" in granted:
-        return fnmatch(required, granted)
-    # A required wildcard is treated as a suffix/prefix requirement for callers.
-    if "*" in required:
-        return fnmatch(granted, required)
-    return False
+    return _has_capabilities([granted], [required])
 
 
 def has_capabilities(granted_caps: list[str], required_caps: list[str]) -> bool:
-    granted = [_normalize_capability(c) for c in granted_caps]
-    for required in required_caps:
-        required = _normalize_capability(required)
-        if not any(capability_matches(g, required) for g in granted):
-            return False
-    return True
+    return _has_capabilities(granted_caps, required_caps)
 
 
 def normalize_capabilities(caps: list[str]) -> list[str]:
-    return sorted({_normalize_capability(cap) for cap in caps})
+    return sorted(normalize_worker_capabilities(caps))
+
+
+def required_capabilities_subset(granted: list[str], required: list[str]) -> bool:
+    return _required_capabilities_subset(granted, required)

active-runtime/app/task_plane/delegation.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from .capabilities import required_capabilities_subset
 from .errors import ConflictError, ForbiddenError, NotFoundError
 from .models import Budget, TaskPlan, TaskRecord
 from .store import TaskPlaneStore
@@ -34,8 +35,9 @@ class DelegationEngine:
     def delegate(self, parent_id: str, child_plan: TaskPlan, *, caller: str) -> TaskRecord:
         self.can_delegate(parent_id, child_plan)
         parent = self.store.get_task(parent_id)
-        if child_plan.required_capabilities and not set(child_plan.required_capabilities).issubset(
-            set(parent.task_plan.required_capabilities or [])
+        if child_plan.required_capabilities and not required_capabilities_subset(
+            parent.task_plan.required_capabilities or [],
+            child_plan.required_capabilities,
         ):
             raise ForbiddenError("child capabilities exceed parent constraints")
         risk_rank = {"low": 1, "medium": 2, "high": 3}

active-runtime/app/task_plane/policy.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Callable
 
+from .capabilities import has_capabilities
 from .errors import ForbiddenError, LockedError
 from .models import ProbeEvidence, ResultEnvelope, TaskRecord
 
@@ -50,7 +51,7 @@ class ReadonlyWorkerProfile:
             return False
         if plan.metadata.get("production_side_effects") is not False:
             return False
-        return set(plan.required_capabilities).issubset(self.capabilities)
+        return has_capabilities(list(self.capabilities), plan.required_capabilities)
 
 
 class IdentityVerifier:

docs/gitops/capability-contract.md

@@ -0,0 +1,31 @@
+# AIOS capability contract
+
+The Agent Task API compares task requirements and worker registrations through one
+strict semantic matcher. Task-facing names are normalized to the worker vocabulary
+before both poll and claim; the two paths cannot disagree about eligibility.
+
+| Task-facing requirement | Semantic capability | Worker vocabulary |
+| --- | --- | --- |
+| repository_read | repo.read | git.read |
+| test_execution | test.execute | git.test |
+| governed_git_write | governed.git.write (composite) | governed.write.branch + governed.write.file |
+
+governed_git_write is composite: a worker must have both the branch-write and
+file-write capabilities. A single component never satisfies the requirement.
+
+Unknown names are not granted by normalization. Wildcard, prefix, and glob
+expressions are never expanded. This is fail-closed: an unknown task
+requirement is never eligible, even if a worker happens to report the same
+unknown string.
+
+The same matcher is used by:
+
+- GET /v1/agent/tasks/poll
+- POST /v1/agent/tasks/{task_id}/claim
+- the compatibility facade in task_plane.capabilities
+
+Legacy runtime names such as shell, git, and python remain exact semantic
+capabilities for compatibility; none implies governed write, production, main, or
+unrestricted command execution. Capability aliases are a compatibility boundary
+only; they do not grant additional authority. Capability strings remain separate
+from Owner credentials, Agent tokens, and WriterLease authorization.

docs/gitops/openapi-agent-task-v1.yaml

@@ -0,0 +1,310 @@
+openapi: 3.1.0
+info:
+  title: AIOS Online Agent Task API
+  version: 1.0.0
+  description: >
+    Durable online task distribution for OpenClaw, Hermes, and other external
+    agents. Agent credentials and lease tokens are bearer credentials and must
+    never be committed to Git.
+servers:
+  - url: /agent-tasks
+paths:
+  /health:
+    get:
+      operationId: agentTaskHealth
+      responses:
+        "200":
+          description: Service health
+  /v1/agents/register:
+    post:
+      operationId: registerOnlineAgent
+      security:
+        - bearerAuth: []
+      description: Control-plane only. Returns the agent token once.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RegisterAgentRequest"
+      responses:
+        "201":
+          description: Registered
+  /v1/tasks:
+    post:
+      operationId: createOnlineAgentTask
+      security:
+        - bearerAuth: []
+      description: Control-plane only.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTaskRequest"
+      responses:
+        "201":
+          description: Task created
+  /v1/tasks/poll:
+    post:
+      operationId: pollOnlineAgentTasks
+      security:
+        - bearerAuth: []
+      description: Agent operation. Returns capability-compatible queued tasks.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  type: integer
+                  minimum: 1
+                  maximum: 100
+                  default: 20
+      responses:
+        "200":
+          description: Available tasks
+  /v1/tasks/{task_id}:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    get:
+      operationId: getOnlineAgentTaskDirect
+      security:
+        - bearerAuth: []
+      responses:
+        "200":
+          description: Task status
+  /v1/tasks/{task_id}/claim:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    post:
+      operationId: claimOnlineAgentTask
+      security:
+        - bearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                lease_seconds:
+                  type: integer
+                  minimum: 30
+                  maximum: 3600
+                  default: 300
+      responses:
+        "200":
+          description: >
+            Claim succeeded. The lease_token is returned once and must be kept
+            in runtime memory/secret storage, never Git.
+        "409":
+          description: Already claimed or otherwise not claimable
+  /v1/tasks/{task_id}/heartbeat:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    post:
+      operationId: heartbeatOnlineAgentTask
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HeartbeatRequest"
+      responses:
+        "200":
+          description: Lease renewed
+  /v1/tasks/{task_id}/result:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    post:
+      operationId: submitOnlineAgentResult
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ResultRequest"
+      responses:
+        "200":
+          description: Result accepted into VERIFYING
+  /v1/tasks/{task_id}/verify:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    post:
+      operationId: verifyOnlineAgentTaskDirect
+      security:
+        - bearerAuth: []
+      description: Control-plane only.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VerifyRequest"
+      responses:
+        "200":
+          description: Verification decision applied
+  /v1/tasks/{task_id}/cancel:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    post:
+      operationId: cancelOnlineAgentTaskDirect
+      security:
+        - bearerAuth: []
+      description: Control-plane only.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+      responses:
+        "200":
+          description: Cancelled or already terminal
+  /v1/tasks/{task_id}/events:
+    parameters:
+      - $ref: "#/components/parameters/TaskId"
+    get:
+      operationId: getOnlineAgentTaskEventsDirect
+      security:
+        - bearerAuth: []
+      description: Control-plane only.
+      responses:
+        "200":
+          description: Audit event list
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    TaskId:
+      name: task_id
+      in: path
+      required: true
+      schema:
+        type: string
+        pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{2,179}$"
+  schemas:
+    RegisterAgentRequest:
+      type: object
+      additionalProperties: false
+      required: [agent_id, agent_type, agent_version, capabilities]
+      properties:
+        agent_id:
+          type: string
+        agent_type:
+          type: string
+          examples: [openclaw]
+        agent_version:
+          type: string
+        capabilities:
+          type: array
+          items:
+            type: string
+        metadata:
+          type: object
+          additionalProperties: true
+    CreateTaskRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - goal
+        - instructions
+        - success_criteria
+        - idempotency_key
+      properties:
+        task_id:
+          type: string
+        goal:
+          type: string
+        instructions:
+          type: string
+        success_criteria:
+          type: array
+          items: {}
+        required_capabilities:
+          type: array
+          items:
+            type: string
+        constraints:
+          type: object
+          additionalProperties: true
+        metadata:
+          type: object
+          additionalProperties: true
+        deadline:
+          type: string
+          format: date-time
+        priority:
+          type: integer
+          minimum: -100
+          maximum: 100
+          default: 0
+        max_attempts:
+          type: integer
+          minimum: 1
+          maximum: 20
+          default: 3
+        idempotency_key:
+          type: string
+    HeartbeatRequest:
+      type: object
+      additionalProperties: false
+      required: [lease_token]
+      properties:
+        lease_token:
+          type: string
+        lease_seconds:
+          type: integer
+          minimum: 30
+          maximum: 3600
+          default: 300
+        progress:
+          type: object
+          additionalProperties: true
+    ResultRequest:
+      type: object
+      additionalProperties: false
+      required: [lease_token, idempotency_key, result]
+      properties:
+        lease_token:
+          type: string
+        idempotency_key:
+          type: string
+        result:
+          type: object
+          additionalProperties: true
+    VerifyRequest:
+      type: object
+      additionalProperties: false
+      required: [decision]
+      properties:
+        decision:
+          type: string
+          enum: [SUCCEEDED, NEEDS_REWORK, FAILED]
+        verification:
+          type: object
+          additionalProperties: true
+x-aios-capability-contract:
+  description: >
+    Task-facing semantic capability names are normalized against the worker
+    runtime vocabulary before eligibility. Unknown and wildcard names fail
+    closed. The composite governed_git_write requirement requires both
+    governed.write.branch and governed.write.file.
+  task_facing:
+    repository_read: repo.read
+    test_execution: test.execute
+    governed_git_write: governed.git.write
+  worker_vocabulary:
+    git.read: repo.read
+    git.test: test.execute
+    governed.write.branch: governed.git.write.branch
+    governed.write.file: governed.git.write.file

docs/gitops/openapi-authorized-task-writer-fragment.yaml

@@ -35,6 +35,7 @@ components:
         target_branch:
           type: string
           pattern: '^agent/[A-Za-z0-9][A-Za-z0-9._/-]{2,179}$'
+          maxLength: 186
         owner_authorization_reference:
           type: string
           minLength: 4

docs/gitops/openapi-owner-authorization-broker-fragment.yaml

@@ -38,6 +38,7 @@ components:
         target_branch:
           type: string
           pattern: '^agent/[A-Za-z0-9][A-Za-z0-9._/-]{2,179}$'
+          maxLength: 186
         one_time_use:
           type: boolean
           const: true

docs/gitops/writer-lease-binding.md

@@ -0,0 +1,19 @@
+# AIOS WriterLease branch binding
+
+A governed branch name is an opaque contract value and must survive the entire
+lifecycle unchanged:
+
+Task.target_branch -> Job.branch -> Lease.branch -> commit request.target_branch -> actual ref
+
+The binding rules are:
+
+- The value must match the governed agent branch grammar and the configured length limit.
+- No truncation, abbreviation, slugging, whitespace trimming, case folding, or inferred replacement is permitted.
+- If a request carries both branch and target_branch, they must be byte-for-byte equal before a job is persisted or a ref is touched.
+- A WriterLease response is checked against the exact requested branch before editing begins.
+- A persisted binding with conflicting aliases is invalid and fails closed as reconciliation-required state; operators must inspect and repair it through the governed path rather than guessing a branch.
+- Overlong or malformed names are validation errors, never shortened values.
+
+The exact value is also checked at commit preflight alongside repository and
+expected base OID. The proof of completion is the exact branch ref and commit OID,
+not merely a successful HTTP response or an active service.

scripts/build_agent_task_api.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Build deterministic immutable staging artifact for AIOS Agent Task API."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import tarfile
+import tempfile
+
+
+REQUIRED = (
+    "active-runtime/app/aios_agent_task_protocol.py",
+    "active-runtime/app/aios_agent_task_api.py",
+    "active-runtime/app/aios_capability_contract.py",
+    "docs/gitops/openapi-agent-task-v1.yaml",
+)
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source-root", required=True, type=Path)
+    parser.add_argument("--output-root", required=True, type=Path)
+    parser.add_argument("--source-oid", required=True)
+    args = parser.parse_args()
+
+    oid = args.source_oid.strip().lower()
+    if len(oid) != 40 or any(ch not in "0123456789abcdef" for ch in oid):
+        raise SystemExit("source oid must be exact 40 hex")
+    source = args.source_root.resolve(strict=True)
+    output = args.output_root.resolve()
+    for relative in REQUIRED:
+        if not (source / relative).is_file():
+            raise SystemExit("required source missing: " + relative)
+
+    output.mkdir(parents=True, exist_ok=True)
+    archive = output / f"aios-agent-task-api-{oid}.tar.gz"
+    manifest = {
+        "schema": "aios.agent-task-artifact.v1",
+        "source_oid": oid,
+        "repository_identity": "aios/aios",
+        "deployment_state": "STAGING",
+        "runtime_mode": "IMMUTABLE_STAGING",
+        "entrypoint": "app/aios_agent_task_api.py",
+        "listen": "127.0.0.1:18940",
+        "plaintext_credentials_in_artifact": False,
+        "included_paths": list(REQUIRED),
+    }
+
+    with tempfile.TemporaryDirectory(prefix="agent-task-build-", dir=str(output)) as temp:
+        stage = Path(temp) / "runtime"
+        for relative in REQUIRED:
+            src = source / relative
+            if relative.startswith("active-runtime/"):
+                dest = stage / Path(relative).relative_to("active-runtime")
+            else:
+                dest = stage / relative
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(src.read_bytes())
+        (stage / "manifest.json").write_text(
+            json.dumps(manifest, sort_keys=True, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        with tarfile.open(archive, "w:gz", format=tarfile.PAX_FORMAT) as tar:
+            for path in sorted(stage.rglob("*")):
+                arcname = str(path.relative_to(stage.parent)).replace("\\", "/")
+                info = tar.gettarinfo(str(path), arcname=arcname)
+                info.mtime = 0
+                info.uid = info.gid = 0
+                info.uname = info.gname = "root"
+                if path.is_file():
+                    with path.open("rb") as fh:
+                        tar.addfile(info, fh)
+                else:
+                    tar.addfile(info)
+
+    receipt = {
+        **manifest,
+        "artifact_path": str(archive),
+        "artifact_sha256": sha256(archive),
+    }
+    receipt_path = archive.with_suffix(archive.suffix + ".receipt.json")
+    receipt_path.write_text(
+        json.dumps(receipt, sort_keys=True, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(receipt, sort_keys=True, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_agent_task_protocol.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+import threading
+
+import pytest
+
+from aios_agent_task_protocol import TaskProtocolError, TaskStore
+
+
+class Clock:
+    def __init__(self) -> None:
+        self.value = datetime(2026, 8, 9, 12, 0, tzinfo=timezone.utc)
+
+    def __call__(self) -> datetime:
+        return self.value
+
+    def advance(self, seconds: int) -> None:
+        self.value += timedelta(seconds=seconds)
+
+
+@pytest.fixture
+def env(tmp_path: Path):
+    clock = Clock()
+    store = TaskStore(tmp_path / "tasks.sqlite3", now=clock, token_pepper="test-pepper")
+    a1 = store.register_agent(
+        agent_id="openclaw-1",
+        agent_type="openclaw",
+        agent_version="test",
+        capabilities=["shell", "git", "python"],
+    )
+    a2 = store.register_agent(
+        agent_id="hermes-1",
+        agent_type="hermes",
+        agent_version="test",
+        capabilities=["shell", "git", "python"],
+    )
+    return store, clock, a1, a2
+
+
+def create_task(store: TaskStore, task_id: str = "TASK-ONLINE-001"):
+    return store.create_task(
+        task_id=task_id,
+        goal="Create a deterministic validation artifact",
+        instructions="Write validation.txt containing ONLINE_TASK_OK.",
+        success_criteria=[
+            {"type": "file_exists", "path": "validation.txt"},
+            {"type": "contains", "path": "validation.txt", "value": "ONLINE_TASK_OK"},
+        ],
+        required_capabilities=["shell"],
+        constraints={"network": "optional"},
+        metadata={"suite": "online-task"},
+        priority=10,
+        max_attempts=3,
+        idempotency_key="create:" + task_id,
+    )
+
+
+def test_full_flow_requires_server_verification(env):
+    store, _clock, a1, _a2 = env
+    create_task(store)
+
+    polled = store.poll_tasks(agent_id=a1["agent_id"])
+    assert [item["task_id"] for item in polled] == ["TASK-ONLINE-001"]
+
+    claim = store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_seconds=300,
+    )
+    assert claim["status"] == "CLAIMED"
+    assert claim["lease_token"].startswith("lease_")
+
+    running = store.heartbeat(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        progress={"percent": 50},
+        lease_seconds=300,
+    )
+    assert running["status"] == "RUNNING"
+
+    submitted = store.submit_result(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="result:1",
+        result={
+            "status": "completed",
+            "summary": "Created validation.txt",
+            "artifacts": [{"path": "validation.txt", "sha256": "0" * 64}],
+        },
+    )
+    assert submitted["status"] == "VERIFYING"
+    assert submitted["status"] != "SUCCEEDED"
+
+    verified = store.verify_task(
+        task_id="TASK-ONLINE-001",
+        decision="SUCCEEDED",
+        verification={"checks": {"content": "PASS"}},
+    )
+    assert verified["status"] == "SUCCEEDED"
+
+
+def test_atomic_claim_allows_only_one_agent(env):
+    store, _clock, a1, a2 = env
+    create_task(store)
+    outcomes: list[tuple[str, str]] = []
+    barrier = threading.Barrier(2)
+
+    def runner(agent_id: str) -> None:
+        barrier.wait()
+        try:
+            store.claim_task(
+                task_id="TASK-ONLINE-001",
+                agent_id=agent_id,
+                lease_seconds=300,
+            )
+            outcomes.append((agent_id, "CLAIMED"))
+        except TaskProtocolError as exc:
+            outcomes.append((agent_id, exc.code))
+
+    t1 = threading.Thread(target=runner, args=(a1["agent_id"],))
+    t2 = threading.Thread(target=runner, args=(a2["agent_id"],))
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    assert sum(result == "CLAIMED" for _, result in outcomes) == 1
+    assert sum(result in {"TASK_NOT_CLAIMABLE", "TASK_CLAIM_CONFLICT"} for _, result in outcomes) == 1
+
+
+def test_expired_lease_is_requeued_and_reclaimable(env):
+    store, clock, a1, a2 = env
+    create_task(store)
+    first = store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_seconds=30,
+    )
+    assert first["attempt"] == 1
+
+    clock.advance(31)
+    available = store.poll_tasks(agent_id=a2["agent_id"])
+    assert available[0]["status"] == "QUEUED"
+
+    second = store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a2["agent_id"],
+        lease_seconds=30,
+    )
+    assert second["attempt"] == 2
+    assert second["claimed_by"] == a2["agent_id"]
+
+
+def test_wrong_lease_token_is_rejected(env):
+    store, _clock, a1, _a2 = env
+    create_task(store)
+    store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_seconds=300,
+    )
+    with pytest.raises(TaskProtocolError, match="TASK_LEASE_TOKEN_INVALID"):
+        store.heartbeat(
+            task_id="TASK-ONLINE-001",
+            agent_id=a1["agent_id"],
+            lease_token="lease_wrong",
+            progress={},
+        )
+
+
+def test_result_submission_is_idempotent(env):
+    store, _clock, a1, _a2 = env
+    create_task(store)
+    claim = store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_seconds=300,
+    )
+    payload = {"status": "completed", "summary": "ok"}
+    first = store.submit_result(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="result:same",
+        result=payload,
+    )
+    second = store.submit_result(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="result:same",
+        result=payload,
+    )
+    assert first["status"] == "VERIFYING"
+    assert second["status"] == "VERIFYING"
+    assert second["idempotent"] is True
+
+    with pytest.raises(TaskProtocolError, match="IDEMPOTENCY_CONFLICT"):
+        store.submit_result(
+            task_id="TASK-ONLINE-001",
+            agent_id=a1["agent_id"],
+            lease_token=claim["lease_token"],
+            idempotency_key="result:same",
+            result={"status": "completed", "summary": "different"},
+        )
+
+
+def test_needs_rework_returns_to_queue(env):
+    store, _clock, a1, _a2 = env
+    create_task(store)
+    claim = store.claim_task(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_seconds=300,
+    )
+    store.submit_result(
+        task_id="TASK-ONLINE-001",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="result:1",
+        result={"status": "completed"},
+    )
+    result = store.verify_task(
+        task_id="TASK-ONLINE-001",
+        decision="NEEDS_REWORK",
+        verification={"reason": "success criteria not met"},
+    )
+    assert result["status"] == "QUEUED"
+    assert result["claimed_by"] is None
+
+
+def test_capability_filter(env):
+    store, _clock, a1, _a2 = env
+    store.create_task(
+        task_id="TASK-GPU-001",
+        goal="GPU task",
+        instructions="Run GPU workload",
+        success_criteria=[],
+        required_capabilities=["gpu"],
+        idempotency_key="create:gpu",
+    )
+    assert store.poll_tasks(agent_id=a1["agent_id"]) == []
+
+
+def test_create_task_idempotency_conflict(env):
+    store, _clock, _a1, _a2 = env
+    first = create_task(store)
+    replay = create_task(store)
+    assert first["task_id"] == replay["task_id"]
+    assert replay["idempotent"] is True
+
+    with pytest.raises(TaskProtocolError, match="IDEMPOTENCY_CONFLICT"):
+        store.create_task(
+            task_id="TASK-ONLINE-002",
+            goal="different",
+            instructions="different",
+            success_criteria=[],
+            idempotency_key="create:TASK-ONLINE-001",
+        )
+
+
+def test_terminal_success_retains_executing_agent_for_final_readback(env):
+    store, _clock, a1, _a2 = env
+    create_task(store, "TASK-TERMINAL-READBACK")
+    claim = store.claim_task(
+        task_id="TASK-TERMINAL-READBACK",
+        agent_id=a1["agent_id"],
+        lease_seconds=120,
+    )
+    store.submit_result(
+        task_id="TASK-TERMINAL-READBACK",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="terminal-result",
+        result={"status": "completed"},
+    )
+    final = store.verify_task(
+        task_id="TASK-TERMINAL-READBACK",
+        decision="SUCCEEDED",
+        verification={"criteria": "PASS"},
+    )
+    assert final["status"] == "SUCCEEDED"
+    assert final["claimed_by"] == a1["agent_id"]
+
+
+def test_needs_rework_releases_agent_ownership_for_reclaim(env):
+    store, _clock, a1, a2 = env
+    create_task(store, "TASK-REWORK-OWNERSHIP")
+    claim = store.claim_task(
+        task_id="TASK-REWORK-OWNERSHIP",
+        agent_id=a1["agent_id"],
+        lease_seconds=120,
+    )
+    store.submit_result(
+        task_id="TASK-REWORK-OWNERSHIP",
+        agent_id=a1["agent_id"],
+        lease_token=claim["lease_token"],
+        idempotency_key="rework-owner-result",
+        result={"status": "completed"},
+    )
+    requeued = store.verify_task(
+        task_id="TASK-REWORK-OWNERSHIP",
+        decision="NEEDS_REWORK",
+        verification={"criteria": "FAIL"},
+    )
+    assert requeued["status"] == "QUEUED"
+    assert requeued["claimed_by"] is None
+    reclaimed = store.claim_task(
+        task_id="TASK-REWORK-OWNERSHIP",
+        agent_id=a2["agent_id"],
+        lease_seconds=120,
+    )
+    assert reclaimed["claimed_by"] == a2["agent_id"]

tests/test_branch_binding_contract.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+
+import pytest
+
+from aios_continuation_lease import ContinuationError, WriterLeaseRequestV2
+from aios_gitops_job_controller import GitOpsJobController, JobError, JobStore
+
+
+BASE_OID = "3244f0f17f8845592ac94d585f5ebd65693c9f29"
+FULL_BRANCH = "agent/r4p0-writerlease-correctness-20260816"
+
+
+class CreateNewProbe:
+    def branch_exists(self, branch):
+        return False
+
+    def commit_exists(self, oid):
+        return True
+
+
+def _job_request(target_branch=FULL_BRANCH, branch=FULL_BRANCH):
+    return {
+        "campaign_id": "governance-contract-remediation-20260816",
+        "repository": "aios/aios",
+        "operation": "GOVERNED_COMMIT",
+        "branch": branch,
+        "target_branch": target_branch,
+        "expected_branch_oid": BASE_OID,
+        "payload_digest": "a" * 64,
+        "idempotency_key": "governance-contract-remediation-v1",
+    }
+
+
+def test_writer_lease_branch_round_trip_preserves_full_regression_value():
+    request = WriterLeaseRequestV2(
+        task_id="governance-contract-remediation-20260816",
+        repository="aios/aios",
+        branch_mode="CREATE_NEW",
+        base_oid=BASE_OID,
+        expected_branch_oid=BASE_OID,
+        target_branch=FULL_BRANCH,
+        generation=1,
+        lease_seconds=900,
+    )
+    request.validate(CreateNewProbe())
+    assert request.target_branch == FULL_BRANCH
+
+
+def test_job_binding_round_trip_keeps_branch_and_target_branch_exact(tmp_path):
+    store = JobStore(str(tmp_path / "jobs"))
+    receipt = GitOpsJobController(store).submit(_job_request())
+    binding = store.read(receipt.job_id)
+    assert binding["branch"] == FULL_BRANCH
+    assert json.loads(binding["request_json"])["binding"]["target_branch"] == FULL_BRANCH
+
+
+def test_mismatched_alias_fails_closed_before_persisting_job(tmp_path):
+    root = tmp_path / "jobs"
+    store = JobStore(str(root))
+    request = _job_request(
+        target_branch="agent/r4p0-writerlease-correctness-2026",
+        branch=FULL_BRANCH,
+    )
+    with pytest.raises(JobError, match="TARGET_BRANCH_BINDING_CONFLICT"):
+        GitOpsJobController(store).submit(request)
+
+    connection = sqlite3.connect(root / "state.sqlite3")
+    try:
+        assert connection.execute("SELECT COUNT(*) FROM jobs").fetchone()[0] == 0
+    finally:
+        connection.close()
+
+
+def test_damaged_persisted_alias_fails_closed(tmp_path):
+    root = tmp_path / "jobs"
+    store = JobStore(str(root))
+    receipt = GitOpsJobController(store).submit(_job_request())
+    connection = sqlite3.connect(root / "state.sqlite3")
+    try:
+        damaged = json.dumps({"binding": {**_job_request(), "target_branch": "agent/r4p0-writerlease-correctness-2026"}})
+        connection.execute("UPDATE jobs SET request_json=? WHERE job_id=?", (damaged, receipt.job_id))
+        connection.commit()
+    finally:
+        connection.close()
+    with pytest.raises(JobError, match="TARGET_BRANCH_BINDING_CONFLICT"):
+        store.read(receipt.job_id)
+
+
+def test_overlong_branch_is_rejected_without_shortening():
+    overlong = "agent/" + ("a" * 181)
+    request = WriterLeaseRequestV2(
+        task_id="governance-contract-remediation-20260816",
+        repository="aios/aios",
+        branch_mode="CREATE_NEW",
+        base_oid=BASE_OID,
+        expected_branch_oid=BASE_OID,
+        target_branch=overlong,
+        generation=1,
+        lease_seconds=900,
+    )
+    with pytest.raises(ContinuationError, match="target_branch_invalid"):
+        request.validate(CreateNewProbe())

tests/test_capability_contract.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import pytest
+
+from aios_capability_contract import (
+    has_capabilities,
+    normalize_required_capabilities,
+    normalize_worker_capabilities,
+)
+from aios_agent_task_protocol import TaskProtocolError, TaskStore
+from task_plane.capabilities import has_capabilities as legacy_has_capabilities
+
+
+def test_task_worker_aliases_and_composite_write():
+    assert has_capabilities(["git.read"], ["repository_read"])
+    assert has_capabilities(["git.test"], ["test_execution"])
+    assert has_capabilities(
+        ["governed.write.branch", "governed.write.file"],
+        ["governed_git_write"],
+    )
+    assert legacy_has_capabilities(["git.read"], ["repository_read"])
+
+
+@pytest.mark.parametrize(
+    ("required", "worker"),
+    [
+        (["governed_git_write"], ["governed.write.file"]),
+        (["governed_git_write"], ["governed.write.branch"]),
+        (["governed.write.branch"], ["governed.write.file"]),
+        (["production.superuser"], ["git.read"]),
+        (["mystery.capability"], ["mystery.capability"]),
+        (["git.*"], ["git.read"]),
+        (["git.read*"], ["git.read"]),
+    ],
+)
+def test_capability_matching_fails_closed(required, worker):
+    assert not has_capabilities(required, worker)
+
+
+def test_security_boundaries_do_not_expand_capabilities():
+    assert not has_capabilities(
+        ["governed.write.branch", "governed.write.file"], ["production.superuser"]
+    )
+    assert not has_capabilities(
+        ["governed.write.branch", "governed.write.file"], ["main.write"]
+    )
+    assert not has_capabilities(["git.test"], ["runtime.shell"])
+    assert not has_capabilities(["git.read"], ["governed_git_write"])
+
+
+def test_duplicate_aliases_normalize_to_one_semantic_capability():
+    assert normalize_required_capabilities(
+        ["repository_read", "git.read", "repo.read"]
+    ) == {"repo.read"}
+    assert normalize_worker_capabilities(["git.read", "repo.read"]) == {"repo.read"}
+
+
+def test_poll_and_claim_share_the_same_matcher(tmp_path):
+    store = TaskStore(tmp_path / "tasks.sqlite3")
+    store.register_agent(
+        agent_id="agent-1",
+        agent_type="test-worker",
+        agent_version="test",
+        capabilities=["git.read", "git.test"],
+    )
+    task_id = "task-capability-contract"
+    store.create_task(
+        task_id=task_id,
+        goal="capability contract",
+        instructions="run the contract test",
+        success_criteria=[],
+        required_capabilities=["repository_read", "test_execution"],
+        idempotency_key="capability-contract-v1",
+    )
+
+    eligible = store.poll_tasks(agent_id="agent-1", limit=10)
+    assert [row["task_id"] for row in eligible] == [task_id]
+
+    claimed = store.claim_task(task_id=task_id, agent_id="agent-1")
+    assert claimed["task_id"] == task_id
+    assert claimed["claimed_by"] == "agent-1"
+
+
+def test_poll_and_claim_reject_the_same_ineligible_worker(tmp_path):
+    store = TaskStore(tmp_path / "tasks.sqlite3")
+    store.register_agent(
+        agent_id="agent-file-only",
+        agent_type="test-worker",
+        agent_version="test",
+        capabilities=["governed.write.file"],
+    )
+    task_id = "task-write-contract"
+    store.create_task(
+        task_id=task_id,
+        goal="write capability contract",
+        instructions="run the contract test",
+        success_criteria=[],
+        required_capabilities=["governed_git_write"],
+        idempotency_key="write-contract-v1",
+    )
+
+    eligible = store.poll_tasks(agent_id="agent-file-only", limit=10)
+    assert eligible == []
+
+    with pytest.raises(TaskProtocolError, match="AGENT_CAPABILITY_MISMATCH"):
+        store.claim_task(task_id=task_id, agent_id="agent-file-only")